@omnitronix/game-engine-sdk 2.0.2 → 2.1.0

package/dist/debug/debug-command-registry.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Debug Command Registry
+ *
+ * A registry pattern implementation for debug commands that provides
+ * a single source of truth for both definitions and execution.
+ *
+ * This eliminates the risk of definition/implementation drift by
+ * co-locating the command metadata with its handler.
+ *
+ * @example
+ * ```typescript
+ * const debugCommands = createDebugCommandRegistry({
+ *   TRIGGER_BONUS: {
+ *     displayName: 'Trigger Bonus',
+ *     description: 'Force-trigger a specific bonus type',
+ *     category: 'bonus',
+ *     parameters: [
+ *       {
+ *         name: 'bonusType',
+ *         displayName: 'Bonus Type',
+ *         type: 'enum',
+ *         enumValues: ['BONUS_GAME', 'FREE_SPIN_AIR', 'FREE_SPIN_WATER'],
+ *       },
+ *     ],
+ *     execute: async (engine, params) => {
+ *       return engine.triggerBonus(params.bonusType);
+ *     },
+ *   },
+ * });
+ *
+ * // Get definitions for dev-tools
+ * const definitions = debugCommands.getDefinitions();
+ *
+ * // Execute a command
+ * const result = await debugCommands.execute('TRIGGER_BONUS', engine, { bonusType: 'BONUS_GAME' });
+ * ```
+ */
+import { DebugCommandDefinition, DebugParameterDefinition } from '@omnitronix/game-engine-contract';
+/**
+ * Handler function type for debug commands.
+ * Receives the game engine instance and validated parameters.
+ */
+export type DebugCommandHandler<TEngine, TParams, TResult> = (engine: TEngine, params: TParams) => Promise<TResult> | TResult;
+/**
+ * Configuration for a single debug command in the registry.
+ */
+export interface DebugCommandConfig<TEngine, TParams = Record<string, unknown>, TResult = unknown> {
+    /**
+     * Human-readable display name
+     */
+    displayName: string;
+    /**
+     * Detailed description of what this command does
+     */
+    description?: string;
+    /**
+     * Grouping category for UI organization
+     */
+    category?: string;
+    /**
+     * Parameter definitions
+     */
+    parameters?: DebugParameterDefinition[];
+    /**
+     * Whether this command can cause issues (shows warning in UI)
+     */
+    dangerous?: boolean;
+    /**
+     * Warning message to display
+     */
+    warningMessage?: string;
+    /**
+     * The command execution handler
+     */
+    execute: DebugCommandHandler<TEngine, TParams, TResult>;
+}
+/**
+ * Registry configuration type.
+ * Maps command codes to their configurations.
+ */
+export type DebugCommandRegistryConfig<TEngine> = {
+    [code: string]: DebugCommandConfig<TEngine, any, any>;
+};
+/**
+ * The debug command registry interface.
+ */
+export interface DebugCommandRegistry<TEngine> {
+    /**
+     * Get all command definitions (for dev-tools).
+     * Safe to call - strips execute handlers before returning.
+     */
+    getDefinitions(): DebugCommandDefinition[];
+    /**
+     * Execute a debug command by code.
+     *
+     * @param code - The command code to execute
+     * @param engine - The game engine instance
+     * @param params - The command parameters
+     * @throws Error if command code is not found
+     */
+    execute<TResult = unknown>(code: string, engine: TEngine, params: Record<string, unknown>): Promise<TResult>;
+    /**
+     * Check if a command code exists in the registry.
+     */
+    hasCommand(code: string): boolean;
+    /**
+     * Get list of all registered command codes.
+     */
+    getCommandCodes(): string[];
+}
+/**
+ * Creates a debug command registry with type-safe definitions and handlers.
+ *
+ * The registry pattern ensures that:
+ * 1. Definitions and handlers are always in sync (single source of truth)
+ * 2. Type safety is maintained for parameters
+ * 3. Unknown commands throw clear errors
+ *
+ * @param config - Map of command codes to their configurations
+ * @returns A registry object with getDefinitions() and execute() methods
+ *
+ * @example
+ * ```typescript
+ * const registry = createDebugCommandRegistry({
+ *   FORCE_WIN: {
+ *     displayName: 'Force Win',
+ *     description: 'Force the next spin to be a winning spin',
+ *     category: 'testing',
+ *     parameters: [
+ *       { name: 'multiplier', displayName: 'Win Multiplier', type: 'number', min: 1, max: 100 },
+ *     ],
+ *     execute: async (engine, { multiplier }) => {
+ *       return engine.setNextWinMultiplier(multiplier);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function createDebugCommandRegistry<TEngine>(config: DebugCommandRegistryConfig<TEngine>): DebugCommandRegistry<TEngine>;
+/**
+ * Security error thrown when debug features are accessed in production.
+ */
+export declare class DebugSecurityError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Production guard wrapper for debug definitions.
+ *
+ * Throws DebugSecurityError in production environments as defense-in-depth.
+ * This should be called at the start of getDebugCommandDefinitions().
+ *
+ * @param logger - Optional logger for audit logging
+ * @throws DebugSecurityError if NODE_ENV is 'production'
+ *
+ * @example
+ * ```typescript
+ * getDebugCommandDefinitions(): DebugCommandDefinition[] {
+ *   assertNotProduction(this.logger);
+ *   return this.debugRegistry.getDefinitions();
+ * }
+ * ```
+ */
+export declare function assertNotProduction(logger?: {
+    warn: (msg: string, ctx?: object) => void;
+}): void;
+/**
+ * Wraps a getDebugCommandDefinitions implementation with production guard.
+ *
+ * @param getDefinitions - The function that returns definitions
+ * @param logger - Optional logger for audit logging
+ * @returns A wrapped function that throws in production
+ *
+ * @example
+ * ```typescript
+ * class MyEngine implements DebugIntrospectable {
+ *   getDebugCommandDefinitions = withProductionGuard(
+ *     () => this.debugRegistry.getDefinitions(),
+ *     this.logger,
+ *   );
+ * }
+ * ```
+ */
+export declare function withProductionGuard(getDefinitions: () => DebugCommandDefinition[], logger?: {
+    warn: (msg: string, ctx?: object) => void;
+}): () => DebugCommandDefinition[];
+//# sourceMappingURL=debug-command-registry.d.ts.map

package/dist/debug/debug-command-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-command-registry.d.ts","sourceRoot":"","sources":["../../src/debug/debug-command-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACzB,MAAM,kCAAkC,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,CAC3D,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,OAAO,KACZ,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO;IAC/F;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,UAAU,CAAC,EAAE,wBAAwB,EAAE,CAAC;IAExC;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,OAAO,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,MAAM,0BAA0B,CAAC,OAAO,IAAI;IAChD,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;CACvD,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,OAAO;IAC3C;;;OAGG;IACH,cAAc,IAAI,sBAAsB,EAAE,CAAC;IAE3C;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,GAAG,OAAO,EACvB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC;;OAEG;IACH,eAAe,IAAI,MAAM,EAAE,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAChD,MAAM,EAAE,0BAA0B,CAAC,OAAO,CAAC,GAC1C,oBAAoB,CAAC,OAAO,CAAC,CA6C/B;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,GAAE,MAAyD;CAI/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAAG,IAAI,CAQhG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,sBAAsB,EAAE,EAC9C,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACrD,MAAM,sBAAsB,EAAE,CAKhC"}

package/dist/debug/debug-command-registry.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Debug Command Registry
+ *
+ * A registry pattern implementation for debug commands that provides
+ * a single source of truth for both definitions and execution.
+ *
+ * This eliminates the risk of definition/implementation drift by
+ * co-locating the command metadata with its handler.
+ *
+ * @example
+ * ```typescript
+ * const debugCommands = createDebugCommandRegistry({
+ *   TRIGGER_BONUS: {
+ *     displayName: 'Trigger Bonus',
+ *     description: 'Force-trigger a specific bonus type',
+ *     category: 'bonus',
+ *     parameters: [
+ *       {
+ *         name: 'bonusType',
+ *         displayName: 'Bonus Type',
+ *         type: 'enum',
+ *         enumValues: ['BONUS_GAME', 'FREE_SPIN_AIR', 'FREE_SPIN_WATER'],
+ *       },
+ *     ],
+ *     execute: async (engine, params) => {
+ *       return engine.triggerBonus(params.bonusType);
+ *     },
+ *   },
+ * });
+ *
+ * // Get definitions for dev-tools
+ * const definitions = debugCommands.getDefinitions();
+ *
+ * // Execute a command
+ * const result = await debugCommands.execute('TRIGGER_BONUS', engine, { bonusType: 'BONUS_GAME' });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DebugSecurityError = void 0;
+exports.createDebugCommandRegistry = createDebugCommandRegistry;
+exports.assertNotProduction = assertNotProduction;
+exports.withProductionGuard = withProductionGuard;
+/**
+ * Creates a debug command registry with type-safe definitions and handlers.
+ *
+ * The registry pattern ensures that:
+ * 1. Definitions and handlers are always in sync (single source of truth)
+ * 2. Type safety is maintained for parameters
+ * 3. Unknown commands throw clear errors
+ *
+ * @param config - Map of command codes to their configurations
+ * @returns A registry object with getDefinitions() and execute() methods
+ *
+ * @example
+ * ```typescript
+ * const registry = createDebugCommandRegistry({
+ *   FORCE_WIN: {
+ *     displayName: 'Force Win',
+ *     description: 'Force the next spin to be a winning spin',
+ *     category: 'testing',
+ *     parameters: [
+ *       { name: 'multiplier', displayName: 'Win Multiplier', type: 'number', min: 1, max: 100 },
+ *     ],
+ *     execute: async (engine, { multiplier }) => {
+ *       return engine.setNextWinMultiplier(multiplier);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+function createDebugCommandRegistry(config) {
+    // Pre-compute definitions at creation time (immutable)
+    const definitions = Object.entries(config).map(([code, cmdConfig]) => ({
+        code,
+        commandType: `DEBUG_${code}`,
+        displayName: cmdConfig.displayName,
+        description: cmdConfig.description,
+        category: cmdConfig.category,
+        parameters: cmdConfig.parameters,
+        dangerous: cmdConfig.dangerous,
+        warningMessage: cmdConfig.warningMessage,
+    }));
+    return {
+        getDefinitions() {
+            // Return a copy to prevent external mutation
+            return [...definitions];
+        },
+        async execute(code, engine, params) {
+            const cmdConfig = config[code];
+            if (!cmdConfig) {
+                const available = Object.keys(config).join(', ');
+                throw new Error(`Unknown debug command: '${code}'. Available commands: ${available}`);
+            }
+            return cmdConfig.execute(engine, params);
+        },
+        hasCommand(code) {
+            return code in config;
+        },
+        getCommandCodes() {
+            return Object.keys(config);
+        },
+    };
+}
+/**
+ * Security error thrown when debug features are accessed in production.
+ */
+class DebugSecurityError extends Error {
+    constructor(message = 'Debug features are not available in production') {
+        super(message);
+        this.name = 'DebugSecurityError';
+    }
+}
+exports.DebugSecurityError = DebugSecurityError;
+/**
+ * Production guard wrapper for debug definitions.
+ *
+ * Throws DebugSecurityError in production environments as defense-in-depth.
+ * This should be called at the start of getDebugCommandDefinitions().
+ *
+ * @param logger - Optional logger for audit logging
+ * @throws DebugSecurityError if NODE_ENV is 'production'
+ *
+ * @example
+ * ```typescript
+ * getDebugCommandDefinitions(): DebugCommandDefinition[] {
+ *   assertNotProduction(this.logger);
+ *   return this.debugRegistry.getDefinitions();
+ * }
+ * ```
+ */
+function assertNotProduction(logger) {
+    if (process.env.NODE_ENV === 'production') {
+        logger?.warn('Attempted to access debug definitions in production', {
+            timestamp: new Date().toISOString(),
+            nodeEnv: process.env.NODE_ENV,
+        });
+        throw new DebugSecurityError();
+    }
+}
+/**
+ * Wraps a getDebugCommandDefinitions implementation with production guard.
+ *
+ * @param getDefinitions - The function that returns definitions
+ * @param logger - Optional logger for audit logging
+ * @returns A wrapped function that throws in production
+ *
+ * @example
+ * ```typescript
+ * class MyEngine implements DebugIntrospectable {
+ *   getDebugCommandDefinitions = withProductionGuard(
+ *     () => this.debugRegistry.getDefinitions(),
+ *     this.logger,
+ *   );
+ * }
+ * ```
+ */
+function withProductionGuard(getDefinitions, logger) {
+    return () => {
+        assertNotProduction(logger);
+        return getDefinitions();
+    };
+}

package/dist/debug/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Debug Command Infrastructure
+ *
+ * Provides utilities for game engines to implement DebugIntrospectable interface
+ * with the registry pattern for type-safe, single-source-of-truth debug commands.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createDebugCommandRegistry,
+ *   withProductionGuard,
+ *   DebugCommandRegistry,
+ * } from '@omnitronix/game-engine-sdk/debug';
+ *
+ * const debugRegistry = createDebugCommandRegistry({
+ *   TRIGGER_BONUS: {
+ *     displayName: 'Trigger Bonus',
+ *     description: 'Force trigger a bonus round',
+ *     category: 'bonus',
+ *     execute: async (engine, params) => engine.triggerBonus(params.bonusType),
+ *   },
+ * });
+ * ```
+ */
+export { createDebugCommandRegistry, assertNotProduction, withProductionGuard, DebugSecurityError, DebugCommandHandler, DebugCommandConfig, DebugCommandRegistryConfig, DebugCommandRegistry, } from './debug-command-registry';
+//# sourceMappingURL=index.d.ts.map

package/dist/debug/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/debug/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAEL,0BAA0B,EAE1B,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAElB,mBAAmB,EACnB,kBAAkB,EAClB,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,0BAA0B,CAAC"}

package/dist/debug/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Debug Command Infrastructure
+ *
+ * Provides utilities for game engines to implement DebugIntrospectable interface
+ * with the registry pattern for type-safe, single-source-of-truth debug commands.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createDebugCommandRegistry,
+ *   withProductionGuard,
+ *   DebugCommandRegistry,
+ * } from '@omnitronix/game-engine-sdk/debug';
+ *
+ * const debugRegistry = createDebugCommandRegistry({
+ *   TRIGGER_BONUS: {
+ *     displayName: 'Trigger Bonus',
+ *     description: 'Force trigger a bonus round',
+ *     category: 'bonus',
+ *     execute: async (engine, params) => engine.triggerBonus(params.bonusType),
+ *   },
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DebugSecurityError = exports.withProductionGuard = exports.assertNotProduction = exports.createDebugCommandRegistry = void 0;
+var debug_command_registry_1 = require("./debug-command-registry");
+// Registry factory
+Object.defineProperty(exports, "createDebugCommandRegistry", { enumerable: true, get: function () { return debug_command_registry_1.createDebugCommandRegistry; } });
+// Production guards
+Object.defineProperty(exports, "assertNotProduction", { enumerable: true, get: function () { return debug_command_registry_1.assertNotProduction; } });
+Object.defineProperty(exports, "withProductionGuard", { enumerable: true, get: function () { return debug_command_registry_1.withProductionGuard; } });
+Object.defineProperty(exports, "DebugSecurityError", { enumerable: true, get: function () { return debug_command_registry_1.DebugSecurityError; } });

package/dist/esm/debug/debug-command-registry.js

@@ -0,0 +1,156 @@
+/**
+ * Debug Command Registry
+ *
+ * A registry pattern implementation for debug commands that provides
+ * a single source of truth for both definitions and execution.
+ *
+ * This eliminates the risk of definition/implementation drift by
+ * co-locating the command metadata with its handler.
+ *
+ * @example
+ * ```typescript
+ * const debugCommands = createDebugCommandRegistry({
+ *   TRIGGER_BONUS: {
+ *     displayName: 'Trigger Bonus',
+ *     description: 'Force-trigger a specific bonus type',
+ *     category: 'bonus',
+ *     parameters: [
+ *       {
+ *         name: 'bonusType',
+ *         displayName: 'Bonus Type',
+ *         type: 'enum',
+ *         enumValues: ['BONUS_GAME', 'FREE_SPIN_AIR', 'FREE_SPIN_WATER'],
+ *       },
+ *     ],
+ *     execute: async (engine, params) => {
+ *       return engine.triggerBonus(params.bonusType);
+ *     },
+ *   },
+ * });
+ *
+ * // Get definitions for dev-tools
+ * const definitions = debugCommands.getDefinitions();
+ *
+ * // Execute a command
+ * const result = await debugCommands.execute('TRIGGER_BONUS', engine, { bonusType: 'BONUS_GAME' });
+ * ```
+ */
+/**
+ * Creates a debug command registry with type-safe definitions and handlers.
+ *
+ * The registry pattern ensures that:
+ * 1. Definitions and handlers are always in sync (single source of truth)
+ * 2. Type safety is maintained for parameters
+ * 3. Unknown commands throw clear errors
+ *
+ * @param config - Map of command codes to their configurations
+ * @returns A registry object with getDefinitions() and execute() methods
+ *
+ * @example
+ * ```typescript
+ * const registry = createDebugCommandRegistry({
+ *   FORCE_WIN: {
+ *     displayName: 'Force Win',
+ *     description: 'Force the next spin to be a winning spin',
+ *     category: 'testing',
+ *     parameters: [
+ *       { name: 'multiplier', displayName: 'Win Multiplier', type: 'number', min: 1, max: 100 },
+ *     ],
+ *     execute: async (engine, { multiplier }) => {
+ *       return engine.setNextWinMultiplier(multiplier);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createDebugCommandRegistry(config) {
+    // Pre-compute definitions at creation time (immutable)
+    const definitions = Object.entries(config).map(([code, cmdConfig]) => ({
+        code,
+        commandType: `DEBUG_${code}`,
+        displayName: cmdConfig.displayName,
+        description: cmdConfig.description,
+        category: cmdConfig.category,
+        parameters: cmdConfig.parameters,
+        dangerous: cmdConfig.dangerous,
+        warningMessage: cmdConfig.warningMessage,
+    }));
+    return {
+        getDefinitions() {
+            // Return a copy to prevent external mutation
+            return [...definitions];
+        },
+        async execute(code, engine, params) {
+            const cmdConfig = config[code];
+            if (!cmdConfig) {
+                const available = Object.keys(config).join(', ');
+                throw new Error(`Unknown debug command: '${code}'. Available commands: ${available}`);
+            }
+            return cmdConfig.execute(engine, params);
+        },
+        hasCommand(code) {
+            return code in config;
+        },
+        getCommandCodes() {
+            return Object.keys(config);
+        },
+    };
+}
+/**
+ * Security error thrown when debug features are accessed in production.
+ */
+export class DebugSecurityError extends Error {
+    constructor(message = 'Debug features are not available in production') {
+        super(message);
+        this.name = 'DebugSecurityError';
+    }
+}
+/**
+ * Production guard wrapper for debug definitions.
+ *
+ * Throws DebugSecurityError in production environments as defense-in-depth.
+ * This should be called at the start of getDebugCommandDefinitions().
+ *
+ * @param logger - Optional logger for audit logging
+ * @throws DebugSecurityError if NODE_ENV is 'production'
+ *
+ * @example
+ * ```typescript
+ * getDebugCommandDefinitions(): DebugCommandDefinition[] {
+ *   assertNotProduction(this.logger);
+ *   return this.debugRegistry.getDefinitions();
+ * }
+ * ```
+ */
+export function assertNotProduction(logger) {
+    if (process.env.NODE_ENV === 'production') {
+        logger?.warn('Attempted to access debug definitions in production', {
+            timestamp: new Date().toISOString(),
+            nodeEnv: process.env.NODE_ENV,
+        });
+        throw new DebugSecurityError();
+    }
+}
+/**
+ * Wraps a getDebugCommandDefinitions implementation with production guard.
+ *
+ * @param getDefinitions - The function that returns definitions
+ * @param logger - Optional logger for audit logging
+ * @returns A wrapped function that throws in production
+ *
+ * @example
+ * ```typescript
+ * class MyEngine implements DebugIntrospectable {
+ *   getDebugCommandDefinitions = withProductionGuard(
+ *     () => this.debugRegistry.getDefinitions(),
+ *     this.logger,
+ *   );
+ * }
+ * ```
+ */
+export function withProductionGuard(getDefinitions, logger) {
+    return () => {
+        assertNotProduction(logger);
+        return getDefinitions();
+    };
+}

package/dist/esm/debug/index.js

@@ -0,0 +1,29 @@
+/**
+ * Debug Command Infrastructure
+ *
+ * Provides utilities for game engines to implement DebugIntrospectable interface
+ * with the registry pattern for type-safe, single-source-of-truth debug commands.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createDebugCommandRegistry,
+ *   withProductionGuard,
+ *   DebugCommandRegistry,
+ * } from '@omnitronix/game-engine-sdk/debug';
+ *
+ * const debugRegistry = createDebugCommandRegistry({
+ *   TRIGGER_BONUS: {
+ *     displayName: 'Trigger Bonus',
+ *     description: 'Force trigger a bonus round',
+ *     category: 'bonus',
+ *     execute: async (engine, params) => engine.triggerBonus(params.bonusType),
+ *   },
+ * });
+ * ```
+ */
+export { 
+// Registry factory
+createDebugCommandRegistry, 
+// Production guards
+assertNotProduction, withProductionGuard, DebugSecurityError, } from './debug-command-registry';

package/dist/esm/index.js

@@ -10,6 +10,8 @@ export * from './registration';
 export * from './grpc';
 // Bootstrap
 export { createGameEngineApp } from './bootstrap';
+// Debug command infrastructure
+export * from './debug';
 // Generated proto types (re-exported for convenience)
 export { GameEngineService, ProcessCommandRequestSchema, ProcessCommandResponseSchema, GetGameEngineInfoRequestSchema, GetGameEngineInfoResponseSchema, } from './generated/game-engine_pb';
 export { GameEngineRegistryService, RegisterGameEngineRequestSchema, RegisterGameEngineResponseSchema, } from './generated/game-engine-registry_pb';

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './health';
 export * from './registration';
 export * from './grpc';
 export { createGameEngineApp, GameEngineAppOptions } from './bootstrap';
+export * from './debug';
 export { GameEngineService, ProcessCommandRequest, ProcessCommandRequestSchema, ProcessCommandResponse, ProcessCommandResponseSchema, GetGameEngineInfoRequest, GetGameEngineInfoRequestSchema, GetGameEngineInfoResponse, GetGameEngineInfoResponseSchema, } from './generated/game-engine_pb';
 export { GameEngineRegistryService, RegisterGameEngineRequest, RegisterGameEngineRequestSchema, RegisterGameEngineResponse, RegisterGameEngineResponseSchema, } from './generated/game-engine-registry_pb';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACvB,UAAU,EACV,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAGjB,cAAc,UAAU,CAAC;AAGzB,cAAc,UAAU,CAAC;AAGzB,cAAc,gBAAgB,CAAC;AAG/B,cAAc,QAAQ,CAAC;AAGvB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGxE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,2BAA2B,EAC3B,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,8BAA8B,EAC9B,yBAAyB,EACzB,+BAA+B,GAChC,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,+BAA+B,EAC/B,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,qCAAqC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACvB,UAAU,EACV,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAGjB,cAAc,UAAU,CAAC;AAGzB,cAAc,UAAU,CAAC;AAGzB,cAAc,gBAAgB,CAAC;AAG/B,cAAc,QAAQ,CAAC;AAGvB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGxE,cAAc,SAAS,CAAC;AAGxB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,2BAA2B,EAC3B,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,8BAA8B,EAC9B,yBAAyB,EACzB,+BAA+B,GAChC,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,+BAA+B,EAC/B,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,qCAAqC,CAAC"}

package/dist/index.js

@@ -30,6 +30,8 @@ __exportStar(require("./grpc"), exports);
 // Bootstrap
 var bootstrap_1 = require("./bootstrap");
 Object.defineProperty(exports, "createGameEngineApp", { enumerable: true, get: function () { return bootstrap_1.createGameEngineApp; } });
+// Debug command infrastructure
+__exportStar(require("./debug"), exports);
 // Generated proto types (re-exported for convenience)
 var game_engine_pb_1 = require("./generated/game-engine_pb");
 Object.defineProperty(exports, "GameEngineService", { enumerable: true, get: function () { return game_engine_pb_1.GameEngineService; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnitronix/game-engine-sdk",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Shared NestJS infrastructure SDK for Omnitronix game engine services",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",
@@ -65,6 +65,16 @@
         "types": "./dist/bootstrap/index.d.ts",
         "default": "./dist/bootstrap/index.js"
       }
+    },
+    "./debug": {
+      "import": {
+        "types": "./dist/debug/index.d.ts",
+        "default": "./dist/esm/debug/index.js"
+      },
+      "require": {
+        "types": "./dist/debug/index.d.ts",
+        "default": "./dist/debug/index.js"
+      }
     }
   },
   "scripts": {
@@ -143,7 +153,7 @@
     "@nestjs/platform-express": "^11.0.0",
     "@nestjs/swagger": "^11.0.6",
     "@nestjs/testing": "^11.0.9",
-    "@omnitronix/game-engine-contract": "^1.0.0",
+    "@omnitronix/game-engine-contract": "^1.2.0",
     "@types/express": "^5.0.0",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.17.10",