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

package/dist/{server → runtime/server}/database/database.service.js

@@ -1,25 +1,4 @@
 "use strict";
-/**
- * Database Service
- *
- * Main entry point for database operations. Acts as a factory/wrapper
- * that delegates to the registered database adapter.
- *
- * @example
- * ```typescript
- * import { DatabaseService } from '@open-core/framework/server'
- * import { inject, injectable } from 'tsyringe'
- *
- * @injectable()
- * class UserService {
- *   constructor(@inject(DatabaseService) private db: DatabaseService) {}
- *
- *   async getUser(id: number) {
- *     return this.db.single<User>('SELECT * FROM users WHERE id = ?', [id])
- *   }
- * }
- * ```
- */
 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);
@@ -37,19 +16,22 @@ exports.execute = execute;
 exports.insert = insert;
 exports.transaction = transaction;
 const tsyringe_1 = require("tsyringe");
+const oxmysql_adapter_1 = require("../../../adapters/database/oxmysql.adapter");
+const resource_adapter_1 = require("../../../adapters/database/resource.adapter");
+const adapter_registry_1 = require("./adapter.registry");
 const database_contract_1 = require("./database.contract");
-const oxmysql_adapter_1 = require("./adapters/oxmysql.adapter");
-/**
- * Database Service
- *
- * Singleton service that provides database operations through
- * a pluggable adapter system. Uses oxmysql by default.
- */
+let defaultFactoriesRegistered = false;
+function registerDefaultDatabaseFactories() {
+    if (defaultFactoriesRegistered)
+        return;
+    (0, adapter_registry_1.registerDatabaseAdapterFactory)('resource', () => new resource_adapter_1.ResourceDatabaseAdapter());
+    (0, adapter_registry_1.registerDatabaseAdapterFactory)('oxmysql', () => new oxmysql_adapter_1.OxMySQLAdapter());
+    defaultFactoriesRegistered = true;
+}
 let DatabaseService = class DatabaseService extends database_contract_1.DatabaseContract {
     constructor() {
         super(...arguments);
         this.adapter = null;
-        this.config = {};
         this.isInitialized = false;
     }
     /**
@@ -58,12 +40,20 @@ let DatabaseService = class DatabaseService extends database_contract_1.Database
      * @param config - Database configuration options
      */
     initialize(config = {}) {
+        var _a, _b;
         if (this.isInitialized)
             return;
-        this.config = config;
-        // Use oxmysql by default
+        registerDefaultDatabaseFactories();
         if (!this.adapter) {
-            this.adapter = new oxmysql_adapter_1.OxMySQLAdapter();
+            const adapterName = ((_a = config.adapter) === null || _a === void 0 ? void 0 : _a.trim()) || ((_b = globalThis.GetConvar) === null || _b === void 0 ? void 0 : _b.call(globalThis, 'opencore_db_adapter', '')) || '';
+            if (!adapterName) {
+                throw new Error("[OpenCore] Database adapter is not configured. Set 'opencore_db_adapter' (recommended: 'resource') or call initDatabase({ adapter: 'resource' }).");
+            }
+            const factory = (0, adapter_registry_1.resolveDatabaseAdapterFactory)(adapterName);
+            if (!factory) {
+                throw new Error(`[OpenCore] Unknown database adapter '${adapterName}'. Register it via registerDatabaseAdapterFactory('${adapterName}', factory).`);
+            }
+            this.adapter = factory();
         }
         this.isInitialized = true;
     }
@@ -94,59 +84,55 @@ let DatabaseService = class DatabaseService extends database_contract_1.Database
      * Get the current adapter
      */
     getAdapter() {
-        this.ensureInitialized();
-        return this.adapter;
+        return this.getInitializedAdapter();
     }
     /**
-     * Ensure the service is initialized before operations
+     * Ensure the service is initialized and return the adapter
      */
-    ensureInitialized() {
-        if (!this.adapter) {
-            // Auto-initialize with defaults if not initialized
+    getInitializedAdapter() {
+        if (!this.isInitialized) {
             this.initialize();
         }
+        if (!this.adapter) {
+            throw new Error('[OpenCore] Database adapter not initialized');
+        }
+        return this.adapter;
     }
     /**
      * Execute a query and return all matching rows
      */
     async query(sql, params) {
-        this.ensureInitialized();
-        return this.adapter.query(sql, params);
+        return this.getInitializedAdapter().query(sql, params);
     }
     /**
      * Execute a query and return a single row
      */
     async single(sql, params) {
-        this.ensureInitialized();
-        return this.adapter.single(sql, params);
+        return this.getInitializedAdapter().single(sql, params);
     }
     /**
      * Execute a query and return a single scalar value
      */
     async scalar(sql, params) {
-        this.ensureInitialized();
-        return this.adapter.scalar(sql, params);
+        return this.getInitializedAdapter().scalar(sql, params);
     }
     /**
      * Execute an UPDATE or DELETE statement
      */
     async execute(sql, params) {
-        this.ensureInitialized();
-        return this.adapter.execute(sql, params);
+        return this.getInitializedAdapter().execute(sql, params);
     }
     /**
      * Execute an INSERT statement
      */
     async insert(sql, params) {
-        this.ensureInitialized();
-        return this.adapter.insert(sql, params);
+        return this.getInitializedAdapter().insert(sql, params);
     }
     /**
      * Execute multiple queries within a transaction
      */
     async transaction(queries, sharedParams) {
-        this.ensureInitialized();
-        return this.adapter.transaction(queries, sharedParams);
+        return this.getInitializedAdapter().transaction(queries, sharedParams);
     }
 };
 exports.DatabaseService = DatabaseService;

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

@@ -0,0 +1,5 @@
+export { ResourceDatabaseAdapter } from '../../../adapters/database/resource.adapter';
+export { registerDatabaseAdapterFactory, resolveDatabaseAdapterFactory } from './adapter.registry';
+export { DatabaseContract } from './database.contract';
+export { DatabaseService, execute, getDatabaseService, initDatabase, insert, query, scalar, single, transaction, } from './database.service';
+export type { DatabaseAdapterFactory, DatabaseConfig, ExecuteResult, InsertResult, TransactionInput, TransactionQuery, TransactionQueryTuple, TransactionSharedParams, } from './types';

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

@@ -0,0 +1,25 @@
+"use strict";
+// Types
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transaction = exports.single = exports.scalar = exports.query = exports.insert = exports.initDatabase = exports.getDatabaseService = exports.execute = exports.DatabaseService = exports.DatabaseContract = exports.resolveDatabaseAdapterFactory = exports.registerDatabaseAdapterFactory = exports.ResourceDatabaseAdapter = void 0;
+// Adapters
+var resource_adapter_1 = require("../../../adapters/database/resource.adapter");
+Object.defineProperty(exports, "ResourceDatabaseAdapter", { enumerable: true, get: function () { return resource_adapter_1.ResourceDatabaseAdapter; } });
+var adapter_registry_1 = require("./adapter.registry");
+Object.defineProperty(exports, "registerDatabaseAdapterFactory", { enumerable: true, get: function () { return adapter_registry_1.registerDatabaseAdapterFactory; } });
+Object.defineProperty(exports, "resolveDatabaseAdapterFactory", { enumerable: true, get: function () { return adapter_registry_1.resolveDatabaseAdapterFactory; } });
+// Contract
+var database_contract_1 = require("./database.contract");
+Object.defineProperty(exports, "DatabaseContract", { enumerable: true, get: function () { return database_contract_1.DatabaseContract; } });
+// Service
+// Standalone functions
+var database_service_1 = require("./database.service");
+Object.defineProperty(exports, "DatabaseService", { enumerable: true, get: function () { return database_service_1.DatabaseService; } });
+Object.defineProperty(exports, "execute", { enumerable: true, get: function () { return database_service_1.execute; } });
+Object.defineProperty(exports, "getDatabaseService", { enumerable: true, get: function () { return database_service_1.getDatabaseService; } });
+Object.defineProperty(exports, "initDatabase", { enumerable: true, get: function () { return database_service_1.initDatabase; } });
+Object.defineProperty(exports, "insert", { enumerable: true, get: function () { return database_service_1.insert; } });
+Object.defineProperty(exports, "query", { enumerable: true, get: function () { return database_service_1.query; } });
+Object.defineProperty(exports, "scalar", { enumerable: true, get: function () { return database_service_1.scalar; } });
+Object.defineProperty(exports, "single", { enumerable: true, get: function () { return database_service_1.single; } });
+Object.defineProperty(exports, "transaction", { enumerable: true, get: function () { return database_service_1.transaction; } });

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,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bind = Bind;
+const tsyringe_1 = require("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 {}
+ * ```
+ */
+function Bind(scope = 'singleton') {
+    return (target) => {
+        (0, tsyringe_1.injectable)()(target);
+        if (scope === 'singleton') {
+            (0, tsyringe_1.singleton)()(target);
+        }
+        else {
+            (0, tsyringe_1.scoped)(tsyringe_1.Lifecycle.ResolutionScoped)(target);
+        }
+    };
+}

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

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { ClassConstructor } from '../../../kernel/di/class-constructor';
+import { SecurityMetadata } from '../types/core-exports';
+export interface CommandConfig {
+    /**
+     * The command name (e.g. "revive", "deposit"), used in chat "/revive"
+     */
+    command: string;
+    /**
+     * The command description, maybe "/help revive"
+     */
+    description?: string;
+    /**
+     * The command usage, maybe "/revive <player>"
+     */
+    usage?: string;
+    /**
+     * Optional Zod schema for command argument validation.
+     *
+     * - `z.tuple([...])`: positional args validation.
+     * - `z.object({...})`: named args validation (maps args to parameter names).
+     *
+     * If omitted, the framework auto-validates only primitive arg types (`string|number|boolean|any[]`).
+     */
+    schema?: z.ZodType;
+}
+export interface CommandMetadata extends CommandConfig {
+    methodName: string;
+    target: ClassConstructor;
+    paramTypes: any;
+    paramNames: string[];
+    expectsPlayer: boolean;
+    isPublic?: boolean;
+    /** Security metadata for remote validation */
+    security?: SecurityMetadata;
+}
+/**
+ * Registers a method as a chat command.
+ *
+ * @remarks
+ * Handler rules:
+ * - If the handler has parameters, the first parameter must be `Player`.
+ *
+ * Validation rules:
+ * - If schema is provided:
+ *   - `z.tuple([...])` validates positional args.
+ *   - `z.object({...})` validates named args by mapping chat args to parameter names.
+ * - If schema is omitted, the framework can only auto-validate primitive types
+ *   (`string|number|boolean|any[]`). Complex payloads should use an explicit Zod schema.
+ *
+ * @param configOrName - Command name, full config, or just command name with schema as second arg.
+ * @param schema - Optional Zod schema when using short form @Command("name", schema).
+ *
+ * @throws Error - If applied to a method without a valid descriptor.
+ * @throws Error - If the method has parameters but does not declare `Player` as the first parameter.
+ *
+ * @example
+ * ```ts
+ * import { z, Infer } from '@open-core/framework'
+ *
+ * const AmountSchema = z.object({ amount: z.number() })
+ *
+ * @Server.Controller()
+ * export class BankController {
+ *   // Simple command (no schema)
+ *   @Server.Command('help')
+ *   help(player: Player) { }
+ *
+ *   // With schema directly (recommended)
+ *   @Server.Command('deposit', AmountSchema)
+ *   deposit(player: Player, data: Infer<typeof AmountSchema>) { }
+ *
+ *   // With full config object (for description, usage, etc.)
+ *   @Server.Command({ command: 'withdraw', schema: AmountSchema, usage: '/withdraw <amount>' })
+ *   withdraw(player: Player, data: Infer<typeof AmountSchema>) { }
+ * }
+ * ```
+ */
+export declare function Command(name: string, schema: z.ZodType): MethodDecorator;
+export declare function Command(name: string): MethodDecorator;
+export declare function Command(config: CommandConfig): MethodDecorator;

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

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Command = Command;
+const player_1 = require("../entities/player");
+const function_helper_1 = require("../helpers/function-helper");
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+// Implementation
+function Command(configOrName, schema) {
+    return (target, propertyKey, descriptor) => {
+        var _a;
+        if (!descriptor.value)
+            throw new Error(`@Command(): descriptor.value is undefined for method '${propertyKey}'`);
+        // Build config from various input forms
+        let config;
+        if (typeof configOrName === 'string') {
+            config = { command: configOrName, schema };
+        }
+        else {
+            config = configOrName;
+        }
+        const paramTypes = (_a = Reflect.getMetadata('design:paramtypes', target, propertyKey)) !== null && _a !== void 0 ? _a : [];
+        const expectsPlayer = paramTypes.length > 0 && paramTypes[0] === player_1.Player;
+        if (paramTypes.length > 0 && !expectsPlayer) {
+            throw new Error(`@Command '${config.command}': first parameter must be Player if parameters are present`);
+        }
+        const paramNames = (0, function_helper_1.getParameterNames)(descriptor.value);
+        const metadata = Object.assign(Object.assign({}, config), { methodName: propertyKey, target: target.constructor, paramTypes,
+            paramNames,
+            expectsPlayer });
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.COMMAND, metadata, target, propertyKey);
+    };
+}

package/dist/{server → runtime/server}/decorators/controller.d.ts

@@ -1,12 +1,13 @@
-import type { ClassConstructor } from '../../system/class-constructor';
-export declare const serverControllerRegistry: ClassConstructor[];
+import { ClassConstructor } from '../../../kernel/di/class-constructor';
+export declare const _serverControllerRegistryByResource: Map<string, Set<ClassConstructor>>;
+export declare function getServerControllerRegistry(resourceName?: string): ClassConstructor[];
 /**
  * Class decorator used to mark a class as a Server Controller.
  *
  * This decorator performs the following actions:
  * 1. Marks the class as `@injectable` (via tsyringe) for dependency injection.
  * 2. Defines metadata identifying the class as a 'server' type controller.
- * 3. Automatically adds the class constructor to the `serverControllerRegistry`.
+ * 3. Automatically adds the class constructor to the `_serverControllerRegistryByResource`.
  *
  * @returns The decorator function to apply to the class.
  *

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

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._serverControllerRegistryByResource = void 0;
+exports.getServerControllerRegistry = getServerControllerRegistry;
+exports.Controller = Controller;
+const tsyringe_1 = require("tsyringe");
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+exports._serverControllerRegistryByResource = 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';
+}
+function getServerControllerRegistry(resourceName) {
+    const key = resourceName !== null && resourceName !== void 0 ? resourceName : getCurrentResourceNameSafe();
+    let registry = exports._serverControllerRegistryByResource.get(key);
+    if (!registry) {
+        registry = new Set();
+        exports._serverControllerRegistryByResource.set(key, registry);
+    }
+    return Array.from(registry);
+}
+/**
+ * Class decorator used to mark a class as a Server Controller.
+ *
+ * This decorator performs the following actions:
+ * 1. Marks the class as `@injectable` (via tsyringe) for dependency injection.
+ * 2. Defines metadata identifying the class as a 'server' type controller.
+ * 3. Automatically adds the class constructor to the `_serverControllerRegistryByResource`.
+ *
+ * @returns The decorator function to apply to the class.
+ *
+ * @example
+ * ```ts
+ * import { Controller } from '@core/server/decorators'
+ *
+ * @Server.Controller()
+ * export class PlayerController {
+ *   constructor(private playerService: PlayerService) {
+ *     // Dependency injection works automatically here
+ *   }
+ * }
+ * ```
+ */
+function Controller() {
+    return (target) => {
+        (0, tsyringe_1.injectable)()(target);
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.CONTROLLER, { type: 'server' }, target);
+        const key = getCurrentResourceNameSafe();
+        let registry = exports._serverControllerRegistryByResource.get(key);
+        if (!registry) {
+            registry = new Set();
+            exports._serverControllerRegistryByResource.set(key, registry);
+        }
+        registry.add(target);
+    };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Exposes a method as a FiveM server export.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework registers the export so that
+ * other resources can call it via `exports['resourceName'][exportName](...)`.
+ *
+ * @param name - Optional export name. If omitted, the method name is used.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class AccountController {
+ *   @Server.Export('getAccountById')
+ *   getAccountById(id: string) {
+ *     return this.accountService.find(id)
+ *   }
+ * }
+ *
+ * // From another resource:
+ * // const result = exports['core-resource'].getAccountById('1234')
+ * ```
+ */
+export declare function Export(name?: string): (target: any, propertyKey: string) => void;

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

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Export = Export;
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+/**
+ * Exposes a method as a FiveM server export.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework registers the export so that
+ * other resources can call it via `exports['resourceName'][exportName](...)`.
+ *
+ * @param name - Optional export name. If omitted, the method name is used.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class AccountController {
+ *   @Server.Export('getAccountById')
+ *   getAccountById(id: string) {
+ *     return this.accountService.find(id)
+ *   }
+ * }
+ *
+ * // From another resource:
+ * // const result = exports['core-resource'].getAccountById('1234')
+ * ```
+ */
+function Export(name) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.EXPORT, { exportName: name || propertyKey }, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,49 @@
+export interface GuardOptions {
+    /**
+     * Minimum rank required to execute the method.
+     * Permissions and Role/Ranks are defined by your Principal Controller
+     */
+    rank?: number;
+    /**
+     * Permission required to execute the method.
+     * Permissions and Role/Ranks are defined by your Principal Controller
+     */
+    permission?: string;
+}
+/**
+ * Declarative access-control decorator for controller methods.
+ *
+ * @remarks
+ * `@Guard()` protects a method by enforcing rank and/or permission requirements before executing it.
+ *
+ * Requirements are evaluated through {@link PrincipalPort}, which determines whether the
+ * player (first argument of the method) is authorized to perform the action.
+ *
+ * Notes:
+ * - The decorated method must receive a `Server.Player` instance as its first argument.
+ * - In stripped decorator builds (e.g. benchmarks), the `PropertyDescriptor` may be missing.
+ *   In that case the decorator stores metadata only and does not wrap the method.
+ *
+ * @param options - Guard options.
+ * @param options.rank - Minimum rank required.
+ * @param options.permission - Permission required.
+ *
+ * @throws Error - If the method is invoked without a valid `Player` as the first argument.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class FactionController {
+ *   @Server.Guard({ permission: 'factions.manage' })
+ *   async createFaction(player: Server.Player, dto: CreateFactionDTO) {
+ *     return this.service.create(dto)
+ *   }
+ *
+ *   @Server.Guard({ rank: 3 })
+ *   async promoteMember(player: Server.Player, memberID: string) {
+ *     return this.service.promote(player, memberID)
+ *   }
+ * }
+ * ```
+ */
+export declare function Guard(options: GuardOptions): (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;

package/dist/{server → runtime/server}/decorators/guard.js

@@ -1,54 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Guard = Guard;
-const container_1 = require("../container");
-const services_1 = require("../services");
-const logger_1 = require("../../shared/logger");
+const kernel_1 = require("../../../kernel");
+const container_1 = require("../../../kernel/di/container");
+const logger_1 = require("../../../kernel/shared/logger");
+const principal_port_1 = require("../services/ports/principal.port");
 /**
- * Guard
- * ------------------------------------------------------------
  * Declarative access-control decorator for controller methods.
  *
- * `@Guard()` protects a method by enforcing rank and/or
- * permission requirements before executing it.
+ * @remarks
+ * `@Guard()` protects a method by enforcing rank and/or permission requirements before executing it.
  *
- * Requirements are evaluated through the AccessControlService,
- * which determines whether the player (first argument of the
- * method) is authorized to perform the action.
+ * Requirements are evaluated through {@link PrincipalPort}, which determines whether the
+ * player (first argument of the method) is authorized to perform the action.
  *
- * Usage of this decorator allows you to express authorization
- * rules directly at the controller level, promoting a clean
- * and explicit security model.
+ * Notes:
+ * - The decorated method must receive a `Server.Player` instance as its first argument.
+ * - In stripped decorator builds (e.g. benchmarks), the `PropertyDescriptor` may be missing.
+ *   In that case the decorator stores metadata only and does not wrap the method.
  *
- * @param options GuardOptions
- *   - rank: minimum rank required to execute the method.
- *   - permission: specific permission required.
+ * @param options - Guard options.
+ * @param options.rank - Minimum rank required.
+ * @param options.permission - Permission required.
  *
- * Notes:
- * - The decorated method must receive a `Server.Player`
- *   instance as its first argument.
- * - When compiling improperly (e.g., benchmarks, stripped
- *   decorators), the PropertyDescriptor may be missing.
- *   In that case, only metadata is recorded and execution
- *   fallback is disabled. This should *never* occur in a
- *   production environment.
+ * @throws Error - If the method is invoked without a valid `Player` as the first argument.
  *
+ * @example
  * ```ts
+ * @Server.Controller()
  * export class FactionController {
  *   @Server.Guard({ permission: 'factions.manage' })
- *   async createFaction(player: Player, dto: CreateFactionDTO) {
+ *   async createFaction(player: Server.Player, dto: CreateFactionDTO) {
  *     return this.service.create(dto)
  *   }
  *
  *   @Server.Guard({ rank: 3 })
- *   async promoteMember(player: Player, memberID: string) {
+ *   async promoteMember(player: Server.Player, memberID: string) {
  *     return this.service.promote(player, memberID)
  *   }
  * }
  * ```
  */
 function Guard(options) {
-    return function (target, propertyKey, descriptor) {
+    return (target, propertyKey, descriptor) => {
         var _a;
         if (!descriptor) {
             // In benchmarks or edge cases, only register metadata without method wrapping
@@ -68,11 +62,18 @@ function Guard(options) {
                 });
                 throw new Error('Guard Security Error: Context is not a player');
             }
-            const accessControl = container_1.di.resolve(services_1.AccessControlService);
-            await accessControl.enforce(player, {
-                minRank: options.rank,
-                permission: options.permission,
-            });
+            const principal = container_1.di.resolve(principal_port_1.PrincipalPort);
+            try {
+                await principal.enforce(player, options);
+            }
+            catch (error) {
+                // Send user-friendly error message for authorization failures
+                if (error instanceof kernel_1.AppError && error.code === 'AUTH:PERMISSION_DENIED') {
+                    player.send(error.message, 'error');
+                    return;
+                }
+                throw error;
+            }
             return originalMethod.apply(this, args);
         };
         // no need a defined metadata key, as we won't read it later

package/dist/{server → runtime/server}/decorators/index.d.ts

@@ -1,10 +1,13 @@
 export * from './bind';
-export * from './utils';
 export { Command, CommandConfig } from './command';
+export { Controller } from './controller';
+export * from './export';
+export * from './guard';
+export * from './onFiveMEvent';
 export * from './onFrameworkEvent';
 export * from './onNet';
 export * from './onTick';
-export { Controller } from './controller';
-export * from './throttle';
-export * from './guard';
+export * from './public';
 export * from './requiresState';
+export * from './throttle';
+export * from './utils';