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

package/dist/runtime/server/helpers/command-validation.helper.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAndExecuteCommand = validateAndExecuteCommand;
+const zod_1 = __importDefault(require("zod"));
+const kernel_1 = require("../../../kernel");
+const schema_generator_1 = require("../system/schema-generator");
+/**
+ * Centraliza validación de argumentos de comandos.
+ */
+async function validateAndExecuteCommand(meta, player, args, handler) {
+    const paramNames = meta.expectsPlayer ? meta.paramNames.slice(1) : meta.paramNames;
+    let schema = meta.schema;
+    // Caso: comando sin player → no espera argumentos
+    if (!meta.expectsPlayer) {
+        if (args.length > 0) {
+            throw new kernel_1.AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${meta.usage}`, 'client', {
+                usage: meta.usage,
+            });
+        }
+        return await handler();
+    }
+    // Autogenerar esquema si no lo definieron
+    if (!schema) {
+        schema = (0, schema_generator_1.generateSchemaFromTypes)(meta.paramTypes);
+        if (!schema) {
+            if (paramNames.length > 0) {
+                throw new kernel_1.AppError('SCHEMA:MISMATCH', `Command '${meta.command}' has parameters ${paramNames.join(', ')} but no schema was provided.`, 'core');
+            }
+            return await handler(player);
+        }
+    }
+    // OBJETO schema
+    if (schema instanceof zod_1.default.ZodObject) {
+        const keys = Object.keys(schema.shape);
+        for (const p of paramNames) {
+            if (!keys.includes(p)) {
+                throw new kernel_1.AppError('SCHEMA:MISMATCH', `Command '${meta.command}' is missing schema for parameter '${p}'.`, 'core');
+            }
+        }
+        for (const key of keys) {
+            if (!paramNames.includes(key)) {
+                throw new kernel_1.AppError('SCHEMA:MISMATCH', `Schema for command '${meta.command}' defines '${key}', but handler does not.`, 'core');
+            }
+        }
+        const inputObj = {};
+        for (let i = 0; i < paramNames.length; i++) {
+            inputObj[paramNames[i]] = args[i];
+        }
+        const validated = await schema.parseAsync(inputObj).catch(() => {
+            throw new kernel_1.AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${meta.usage}`, 'client', {
+                usage: meta.usage,
+            });
+        });
+        const obj = validated;
+        const finalArgs = paramNames.map((name) => obj[name]);
+        return await handler(player, ...finalArgs);
+    }
+    // TUPLA schema
+    if (schema instanceof zod_1.default.ZodTuple) {
+        const validated = await schema.parseAsync(args).catch(() => {
+            throw new kernel_1.AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${meta.usage}`, 'client', {
+                usage: meta.usage,
+            });
+        });
+        return await handler(player, ...validated);
+    }
+    // fallback
+    return await handler(player);
+}

package/dist/runtime/server/helpers/function-helper.d.ts

@@ -0,0 +1 @@
+export declare function getParameterNames(func: Function): string[];

package/dist/runtime/server/helpers/function-helper.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getParameterNames = getParameterNames;
+function getParameterNames(func) {
+    const stripped = func
+        .toString()
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//gm, '');
+    const args = stripped
+        .slice(stripped.indexOf('(') + 1, stripped.indexOf(')'))
+        .split(',')
+        .map((arg) => arg.replace(/=[\s\S]*/, '').trim())
+        .filter(Boolean);
+    return args;
+}

package/dist/{server → runtime/server}/helpers/resolve-method.d.ts

@@ -1,5 +1,5 @@
 export declare function resolveMethod(instance: Record<string, any>, methodName: string, errorMessage: string): {
-    handler: Function;
+    handler: (...args: any[]) => any;
     handlerName: string;
     proto: any;
 } | undefined;

package/dist/runtime/server/helpers/resolve-method.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMethod = resolveMethod;
+const logger_1 = require("../../../kernel/shared/logger");
+const utils_1 = require("../../../kernel/utils");
+function resolveMethod(instance, methodName, errorMessage) {
+    try {
+        const proto = Object.getPrototypeOf(instance);
+        const method = instance[methodName];
+        if (typeof method !== 'function') {
+            logger_1.loggers.scanner.error(errorMessage, {
+                className: instance.constructor.name,
+                methodName,
+            });
+            return;
+        }
+        const handler = method.bind(instance);
+        const handlerName = `${instance.constructor.name}.${methodName}`;
+        return { handler, handlerName, proto };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new utils_1.AppError('COMMON:UNKNOWN', `[${error.name}] ${error.message}`, 'server', error.stack);
+        }
+        else
+            throw error;
+    }
+}

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

@@ -1,10 +1,12 @@
-export * from './core';
+export * from './bootstrap.validation';
+export * from './configs';
+export * from './contracts/index';
+export { init } from './core';
 export * from './decorators';
-export * from './templates';
-export * from './services';
+export * from './devmode';
 export * from './entities';
-export * from './configs';
+export * from './runtime';
+export * from './services';
 export * from './setup';
+export * from './templates';
 export type * from './types/core-events';
-import './controllers/command.controller';
-import './controllers/chat.controller';

package/dist/{server → runtime/server}/index.js

@@ -1,4 +1,5 @@
 "use strict";
+// Framework modules
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -14,18 +15,21 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// Framework modules
-__exportStar(require("./core"), exports);
+exports.init = void 0;
+__exportStar(require("./bootstrap.validation"), exports);
+// Configs
+__exportStar(require("./configs"), exports);
+__exportStar(require("./contracts/index"), exports);
+var core_1 = require("./core");
+Object.defineProperty(exports, "init", { enumerable: true, get: function () { return core_1.init; } });
 __exportStar(require("./decorators"), exports);
-__exportStar(require("./templates"), exports);
-__exportStar(require("./services"), exports);
+// DevMode (development tools)
+__exportStar(require("./devmode"), exports);
 // Entities
 __exportStar(require("./entities"), exports);
-// Configs
-__exportStar(require("./configs"), exports);
+__exportStar(require("./runtime"), exports);
+__exportStar(require("./services"), exports);
 __exportStar(require("./setup"), exports);
-// Controllers
-require("./controllers/command.controller");
-require("./controllers/chat.controller");
-const container_1 = require("./container");
+__exportStar(require("./templates"), exports);
+const container_1 = require("../../kernel/di/container");
 globalThis.oc_container = container_1.di;

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

@@ -0,0 +1,408 @@
+export type FrameworkMode = 'CORE' | 'RESOURCE' | 'STANDALONE';
+/**
+ * Feature provider source configuration.
+ *
+ * @remarks
+ * Determines where a feature's implementation comes from:
+ *
+ * - `'core'`: Feature provided by CORE resource via exports
+ *   - Used in RESOURCE mode for: players, principal, auth, commands
+ *   - Triggers remote service implementations that delegate to CORE
+ *
+ * - `'local'`: Feature implemented locally in current resource
+ *   - Used in CORE/STANDALONE for all features
+ *   - Used in RESOURCE for: netEvents, fiveMEvents, exports, http, chat, database
+ *   - Triggers local service implementations
+ *
+ * @example
+ * ```typescript
+ * // RESOURCE mode - commands delegate to CORE
+ * commands: { enabled: true, provider: 'core' }
+ *
+ * // STANDALONE mode - commands execute locally
+ * commands: { enabled: true, provider: 'local' }
+ * ```
+ */
+export type FeatureProvider = 'core' | 'local';
+export type FeatureScope = 'core' | 'resource' | 'standalone';
+export type FeatureName = 'players' | 'netEvents' | 'fiveMEvents' | 'commands' | 'exports' | 'http' | 'chat' | 'database' | 'principal' | 'auth' | 'sessionLifecycle';
+/**
+ * Base feature configuration (all features support this).
+ */
+export interface BaseFeatureConfig {
+    /**
+     * Enable or disable this feature.
+     *
+     * @defaultValue Varies by feature and mode (see specific feature docs)
+     */
+    enabled?: boolean;
+}
+/**
+ * Feature configuration with configurable provider.
+ *
+ * @remarks
+ * Only applies to: `players`, `commands`, `principal`, `auth`
+ *
+ * For these features, you can choose:
+ * - `'core'`: Use CORE's implementation (RESOURCE mode)
+ * - `'local'`: Use local implementation (STANDALONE mode)
+ *
+ * **Defaults by mode:**
+ * - CORE: `'core'`
+ * - RESOURCE: `'core'` (delegates to CORE)
+ * - STANDALONE: `'local'`
+ */
+export interface ProviderFeatureConfig extends BaseFeatureConfig {
+    /**
+     * Provider source for this feature.
+     *
+     * @remarks
+     * - RESOURCE mode: Use `'core'` to delegate to CORE (default)
+     * - STANDALONE mode: Must use `'local'` (default)
+     */
+    provider?: FeatureProvider;
+}
+/**
+ * Feature configuration with export option (CORE mode only).
+ *
+ * @remarks
+ * Only applies to: `players`, `principal`, `chat` in CORE mode
+ *
+ * When `export: true`, the feature exposes FiveM exports for RESOURCE mode access.
+ */
+export interface ExportableFeatureConfig extends BaseFeatureConfig {
+    /**
+     * Whether to expose this feature via FiveM exports.
+     *
+     * @remarks
+     * - Only valid in CORE mode
+     * - Requires `exports` feature to be enabled
+     * - Used by RESOURCE mode to access CORE functionality
+     *
+     * @defaultValue false
+     */
+    export?: boolean;
+}
+/**
+ * User-facing feature configuration.
+ *
+ * @remarks
+ * This is what users configure in `Server.init({ features: {...} })`.
+ * Internal fields like `scope` and `required` are auto-managed by the framework.
+ */
+export interface UserFeatureConfig {
+    /**
+     * Player management and directory.
+     *
+     * @remarks
+     * **Dependencies**: None
+     * **Provider**: Configurable
+     * - CORE/STANDALONE: Local player management
+     * - RESOURCE: Delegates to CORE
+     *
+     * **Export** (CORE only): When true, exposes player APIs to RESOURCE mode
+     *
+     * @defaultValue
+     * - enabled: true
+     * - provider: 'core' (RESOURCE), 'core' (CORE), 'local' (STANDALONE)
+     * - export: false
+     */
+    players?: ProviderFeatureConfig & ExportableFeatureConfig;
+    /**
+     * Command registration and execution.
+     *
+     * @remarks
+     * **Dependencies**: Requires `players` to be enabled
+     * **Provider**: Configurable
+     * - CORE/STANDALONE: Local command execution
+     * - RESOURCE: Commands register with CORE for centralized security validation
+     *
+     * **Export** (CORE only): Always exported when enabled (for RESOURCE mode access)
+     *
+     * @defaultValue
+     * - enabled: false
+     * - provider: 'core' (RESOURCE), 'local' (CORE/STANDALONE)
+     * - export: true (CORE only, automatic)
+     */
+    commands?: ProviderFeatureConfig;
+    /**
+     * Principal (identity) provider for permissions.
+     *
+     * @remarks
+     * **Dependencies**: None
+     * **Provider**: Configurable
+     * - CORE: User-provided PrincipalProvider implementation
+     * - RESOURCE: Delegates to CORE
+     * - STANDALONE: User-provided PrincipalProvider implementation
+     *
+     * **Export** (CORE only): When true, exposes principal APIs to RESOURCE mode
+     *
+     * @defaultValue
+     * - enabled: false
+     * - provider: 'core' (RESOURCE), 'core' (CORE), 'local' (STANDALONE)
+     * - export: false
+     */
+    principal?: ProviderFeatureConfig & ExportableFeatureConfig;
+    /**
+     * Authentication provider for login/logout.
+     *
+     * @remarks
+     * **Dependencies**: None
+     * **Provider**: Configurable
+     * - CORE: User-provided AuthProvider implementation
+     * - RESOURCE: Delegates to CORE
+     * - STANDALONE: User-provided AuthProvider implementation
+     *
+     * @defaultValue
+     * - enabled: false
+     * - provider: 'core' (RESOURCE), 'core' (CORE), 'local' (STANDALONE)
+     */
+    auth?: ProviderFeatureConfig;
+    /**
+     * Network events (`onNet` decorator support).
+     *
+     * @remarks
+     * **Dependencies**: Requires `players` to be enabled
+     * **Provider**: Auto-determined (not configurable)
+     * - Always `'local'` (events are handled locally in each resource)
+     *
+     * @defaultValue enabled: true
+     */
+    netEvents?: BaseFeatureConfig;
+    /**
+     * FiveM lifecycle events (`onServer`, `onClient`, etc.).
+     *
+     * @remarks
+     * **Dependencies**: None
+     * **Provider**: Auto-determined (not configurable)
+     * - Always `'local'`
+     * - Disabled in RESOURCE mode (only CORE/STANDALONE need lifecycle management)
+     *
+     * @defaultValue
+     * - enabled: true (CORE/STANDALONE), false (RESOURCE)
+     */
+    fiveMEvents?: BaseFeatureConfig;
+    /**
+     * FiveM exports support (`@Export` decorator).
+     *
+     * @remarks
+     * **Dependencies**: None
+     * **Provider**: Auto-determined (not configurable)
+     * - Always `'local'`
+     *
+     * @defaultValue enabled: false
+     */
+    exports?: BaseFeatureConfig;
+    /**
+     * HTTP server and endpoints.
+     *
+     * @remarks
+     * **Dependencies**: None
+     * **Provider**: Auto-determined (not configurable)
+     * - Always `'local'`
+     *
+     * @defaultValue enabled: false
+     */
+    http?: BaseFeatureConfig;
+    /**
+     * Chat message handling.
+     *
+     * @remarks
+     * **Dependencies**: Requires `players` to be enabled
+     * **Provider**: Auto-determined (not configurable)
+     * - Always `'local'`
+     *
+     * **Export** (CORE only): When true, exposes chat APIs to RESOURCE mode
+     *
+     * @defaultValue
+     * - enabled: false
+     * - export: false
+     */
+    chat?: BaseFeatureConfig & ExportableFeatureConfig;
+    /**
+     * Database access.
+     *
+     * @remarks
+     * **Dependencies**: None
+     * **Provider**: Auto-determined (not configurable)
+     * - Always `'local'`
+     *
+     * @defaultValue enabled: false
+     */
+    database?: BaseFeatureConfig;
+    /**
+     * Session lifecycle management (internal).
+     *
+     * @remarks
+     * **Dependencies**: None
+     * **Provider**: Auto-determined (not configurable)
+     * - Disabled in RESOURCE mode (CORE manages sessions)
+     *
+     * @defaultValue
+     * - enabled: true (CORE/STANDALONE), false (RESOURCE)
+     */
+    sessionLifecycle?: BaseFeatureConfig;
+}
+/**
+ * Internal feature contract with all fields resolved.
+ *
+ * @remarks
+ * This is used internally by the framework after merging user config with defaults.
+ * Users don't interact with this directly.
+ *
+ * @internal
+ */
+export interface FeatureContract {
+    /**
+     * Enables or disables the feature at runtime.
+     *
+     * If `required` is `true`, this must also be `true` (otherwise validation will throw).
+     */
+    enabled: boolean;
+    /**
+     * Determines where the implementation comes from.
+     *
+     * - `core`: feature is provided by the core resource (via exports when applicable)
+     * - `local`: feature is implemented/handled locally by the current runtime (resource/standalone)
+     */
+    provider: FeatureProvider;
+    /**
+     * Marks the feature as exportable via FiveM exports.
+     *
+     * Only meaningful in CORE mode. When `true`, the framework dynamically imports
+     * export controllers that expose the feature's API to RESOURCE mode.
+     */
+    export: boolean;
+    /**
+     * The runtime scope this feature contract is intended for.
+     *
+     * Must match the scope derived from the current FrameworkMode
+     */
+    scope: FeatureScope;
+    /**
+     * Marks the feature as mandatory for the current runtime configuration.
+     *
+     * When `true`, the feature cannot be disabled (`enabled` must be `true`).
+     */
+    required: boolean;
+}
+export type FrameworkFeatures = Record<FeatureName, FeatureContract>;
+export interface ResourceGrants {
+    database?: boolean;
+    principal?: boolean;
+    auth?: boolean;
+}
+export interface DevModeConfig {
+    /** Enable dev mode */
+    enabled: boolean;
+    /** Hot reload configuration */
+    hotReload?: {
+        enabled: boolean;
+        port: number;
+        allowedResources?: string[];
+    };
+    /** CLI bridge configuration */
+    bridge?: {
+        url: string;
+        autoConnect: boolean;
+    };
+    /** Event interceptor configuration */
+    interceptor?: {
+        enabled: boolean;
+        recordHistory: boolean;
+        maxHistorySize: number;
+    };
+    /** Player simulator configuration */
+    simulator?: {
+        enabled: boolean;
+        autoConnectPlayers: number;
+    };
+}
+export interface ServerRuntimeOptions {
+    mode: FrameworkMode;
+    features: FrameworkFeatures;
+    coreResourceName: string;
+    resourceGrants?: ResourceGrants;
+    /** Development mode configuration (disabled in production) */
+    devMode?: DevModeConfig;
+}
+export type RuntimeContext = ServerRuntimeOptions;
+export declare function setRuntimeContext(ctx: RuntimeContext): void;
+export declare function getRuntimeContext(): RuntimeContext;
+export declare function getFrameworkModeScope(mode: FrameworkMode): FeatureScope;
+/**
+ * Server initialization configuration.
+ *
+ * @remarks
+ * Defines the runtime mode and feature configuration for OpenCore.
+ *
+ * @example Minimal CORE Mode
+ * ```typescript
+ * Server.init({
+ *   mode: 'CORE',
+ *   features: {
+ *     commands: { enabled: true },
+ *     principal: { enabled: true },
+ *   }
+ * })
+ * ```
+ *
+ * @example Minimal RESOURCE Mode
+ * ```typescript
+ * Server.init({
+ *   mode: 'RESOURCE',
+ *   coreResourceName: 'my-core',
+ *   features: {
+ *     commands: { enabled: true },  // Auto-uses 'core' provider
+ *   }
+ * })
+ * ```
+ *
+ * @example STANDALONE Mode
+ * ```typescript
+ * Server.init({
+ *   mode: 'STANDALONE',
+ *   features: {
+ *     players: { enabled: true },
+ *     commands: { enabled: true },
+ *   }
+ * })
+ * ```
+ */
+export interface ServerInitOptions {
+    /** Runtime mode determining feature availability and provider sources */
+    mode: FrameworkMode;
+    /**
+     * Feature configuration.
+     *
+     * @remarks
+     * All features have sensible defaults. You only need to configure:
+     * - `enabled: true` to enable a feature
+     * - `provider` (optional, only for players/commands/principal/auth if you want non-default)
+     * - `export: true` (optional, CORE mode only, for players/principal/chat)
+     *
+     * **Most features auto-determine their provider based on mode.**
+     * Only configure `provider` if you need to override defaults.
+     */
+    features?: UserFeatureConfig;
+    /**
+     * Name of the CORE resource.
+     *
+     * @remarks
+     * - **Required in RESOURCE mode** (to locate CORE exports)
+     * - Optional in CORE/STANDALONE modes
+     *
+     * @defaultValue 'core'
+     */
+    coreResourceName?: string;
+    /** Resource grants configuration (CORE mode only) */
+    resourceGrants?: ResourceGrants;
+    /** Development mode configuration (disabled in production) */
+    devMode?: DevModeConfig;
+}
+export declare function resolveRuntimeOptions(options: ServerInitOptions): ServerRuntimeOptions;
+export declare function validateRuntimeOptions(options: ServerRuntimeOptions): void;
+/**
+ * @deprecated Use validateRuntimeOptions instead
+ */
+export declare const validateRuntimeContextOrThrow: typeof validateRuntimeOptions;