unreal-engine-mcp-server 0.5.21 → 0.6.0-a

package/dist/utils/responses/response-factory.js

@@ -0,0 +1,49 @@
+import { cleanObject } from '../serialization/safe-json.js';
+function isAutomationErrorDetail(value) {
+    return !(value instanceof Error)
+        && value !== null
+        && typeof value === 'object'
+        && !Array.isArray(value)
+        && typeof value.message === 'string';
+}
+export class ResponseFactory {
+    static success(data, message = 'Operation successful') {
+        return {
+            success: true,
+            message,
+            data: cleanObject(data)
+        };
+    }
+    static error(error, code) {
+        if (isAutomationErrorDetail(error)) {
+            const detail = cleanObject(error);
+            return {
+                success: false,
+                isError: true,
+                error: detail,
+                message: detail.message,
+                data: null
+            };
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error || 'Operation failed');
+        const response = {
+            success: false,
+            isError: true,
+            message: errorMessage,
+            data: null
+        };
+        if (code)
+            response.error = code;
+        return response;
+    }
+    static errorWithCode(code, message, extraFields) {
+        return cleanObject({
+            success: false,
+            isError: true,
+            error: code,
+            message,
+            ...extraFields
+        });
+    }
+}
+//# sourceMappingURL=response-factory.js.map

package/dist/utils/responses/response-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-factory.js","sourceRoot":"","sources":["../../../src/utils/responses/response-factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAW5D,SAAS,uBAAuB,CAAC,KAAc;IAC3C,OAAO,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;WACzB,KAAK,KAAK,IAAI;WACd,OAAO,KAAK,KAAK,QAAQ;WACzB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;WACrB,OAAQ,KAAiC,CAAC,OAAO,KAAK,QAAQ,CAAC;AAC1E,CAAC;AAED,MAAM,OAAO,eAAe;IAIxB,MAAM,CAAC,OAAO,CAAC,IAAa,EAAE,UAAkB,sBAAsB;QAClE,OAAO;YACH,OAAO,EAAE,IAAI;YACb,OAAO;YACP,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC;SAC1B,CAAC;IACN,CAAC;IAOD,MAAM,CAAC,KAAK,CAAC,KAAc,EAAE,IAAa;QACtC,IAAI,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;YAClC,OAAO;gBACH,OAAO,EAAE,KAAK;gBACd,OAAO,EAAE,IAAI;gBACb,KAAK,EAAE,MAAM;gBACb,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EAAE,IAAI;aACb,CAAC;QACN,CAAC;QAED,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,kBAAkB,CAAC,CAAC;QAElG,MAAM,QAAQ,GAA2B;YACrC,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,YAAY;YACrB,IAAI,EAAE,IAAI;SACb,CAAC;QACF,IAAI,IAAI;YAAE,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC;QAChC,OAAO,QAAQ,CAAC;IACpB,CAAC;IAUD,MAAM,CAAC,aAAa,CAAC,IAAY,EAAE,OAAe,EAAE,WAAqC;QACrF,OAAO,WAAW,CAAC;YACf,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,IAAI;YACX,OAAO;YACP,GAAG,WAAW;SACjB,CAAkB,CAAC;IACxB,CAAC;CACJ"}

package/dist/utils/responses/response-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-validator.d.ts","sourceRoot":"","sources":["../../../src/utils/responses/response-validator.ts"],"names":[],"mappings":"AAaA,qBAAa,iBAAiB;IAE5B,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,UAAU,CAA4C;;IAuB9D,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAmBhE,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC;QACnE,KAAK,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B,CAAC;IA8DI,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IA0HzF,QAAQ;;;;CAMT;AAGD,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}

package/dist/utils/responses/response-validator.js

@@ -0,0 +1,185 @@
+import Ajv from 'ajv';
+import { Logger } from '../logging/logger.js';
+import { buildImageContent, buildSummaryText, hasExplicitFailurePayload } from './response-content.js';
+import { cleanObject } from '../serialization/safe-json.js';
+import { isRecord } from '../validation/type-guards.js';
+const log = new Logger('ResponseValidator');
+export class ResponseValidator {
+    ajv;
+    validators = new Map();
+    constructor() {
+        const AjvClass = Ajv.default ?? Ajv.default;
+        this.ajv = new AjvClass({
+            allErrors: true,
+            verbose: true,
+            strict: true,
+            allowUnionTypes: true
+        });
+        this.ajv.addKeyword({
+            keyword: 'x-unreal-reflection-boundary',
+            schemaType: 'boolean',
+            valid: true
+        });
+    }
+    registerSchema(toolName, outputSchema) {
+        if (!outputSchema) {
+            log.warn(`No output schema defined for tool: ${toolName}`);
+            return;
+        }
+        try {
+            const validator = this.ajv.compile(outputSchema);
+            this.validators.set(toolName, validator);
+            log.debug(`Registered output schema for tool: ${toolName}`);
+        }
+        catch (error) {
+            log.error(`Failed to compile output schema for ${toolName}:`, error instanceof Error ? error : String(error));
+        }
+    }
+    async validateResponse(toolName, response) {
+        const validator = this.validators.get(toolName);
+        if (!validator) {
+            log.debug(`No validator found for tool: ${toolName}`);
+            return { valid: true };
+        }
+        let structuredContent = response;
+        const responseObj = isRecord(response) ? response : null;
+        if (responseObj && responseObj.content && Array.isArray(responseObj.content)) {
+            const textContent = responseObj.content.find((c) => isRecord(c) && c.type === 'text');
+            if (textContent?.text) {
+                const rawText = String(textContent.text);
+                const trimmed = rawText.trim();
+                const looksLikeJson = trimmed.startsWith('{') || trimmed.startsWith('[');
+                if (looksLikeJson) {
+                    try {
+                        structuredContent = JSON.parse(rawText);
+                    }
+                    catch {
+                        structuredContent = response;
+                    }
+                }
+            }
+        }
+        const valid = validator(structuredContent);
+        if (!valid) {
+            const errors = validator.errors?.map((err) => `${err.instancePath || 'root'}: ${err.message}`);
+            log.warn(`Response validation failed for ${toolName}:`, errors);
+            return {
+                valid: false,
+                errors,
+                structuredContent
+            };
+        }
+        return {
+            valid: true,
+            structuredContent
+        };
+    }
+    async wrapResponse(toolName, response) {
+        let safeResponse = response;
+        try {
+            if (response && typeof response === 'object') {
+                JSON.stringify(response);
+            }
+        }
+        catch (error) {
+            log.error(`Response for ${toolName} contains circular references, cleaning...`, error instanceof Error ? error : String(error));
+            safeResponse = cleanObject(response);
+        }
+        const responseObj = isRecord(safeResponse) ? safeResponse : null;
+        const alreadyMcpShaped = responseObj && typeof responseObj === 'object' && Array.isArray(responseObj.content);
+        const validation = await this.validateResponse(toolName, safeResponse);
+        const structuredPayload = validation.structuredContent;
+        if (!validation.valid) {
+            log.warn(`Tool ${toolName} response validation failed:`, validation.errors);
+        }
+        if (alreadyMcpShaped && responseObj) {
+            if (structuredPayload !== undefined && responseObj.structuredContent === undefined) {
+                try {
+                    responseObj.structuredContent = structuredPayload && typeof structuredPayload === 'object'
+                        ? cleanObject(structuredPayload)
+                        : structuredPayload;
+                }
+                catch (error) {
+                    log.debug(`Unable to attach structured content for ${toolName}`, error instanceof Error ? error : String(error));
+                }
+            }
+            const structuredContent = responseObj.structuredContent ?? structuredPayload;
+            if ((hasExplicitFailurePayload(structuredContent) || hasExplicitFailurePayload(responseObj)) && responseObj.isError !== true) {
+                responseObj.isError = true;
+            }
+            if (!validation.valid) {
+                try {
+                    responseObj._validation = { valid: false, errors: validation.errors };
+                }
+                catch (error) {
+                    log.debug(`Unable to attach validation metadata for ${toolName}`, error instanceof Error ? error : String(error));
+                }
+            }
+            const imageContent = buildImageContent(responseObj.structuredContent ?? structuredPayload);
+            if (imageContent && Array.isArray(responseObj.content)) {
+                const hasImageContent = responseObj.content.some((part) => isRecord(part) && part.type === 'image');
+                if (!hasImageContent) {
+                    responseObj.content.push(imageContent);
+                }
+            }
+            return responseObj;
+        }
+        const summarySource = structuredPayload !== undefined ? structuredPayload : safeResponse;
+        let text = buildSummaryText(toolName, summarySource);
+        if (!text || !text.trim()) {
+            text = buildSummaryText(toolName, safeResponse);
+        }
+        const wrapped = {
+            content: [
+                { type: 'text', text }
+            ]
+        };
+        if (isRecord(structuredPayload) && typeof structuredPayload.success === 'boolean') {
+            wrapped.success = Boolean(structuredPayload.success);
+        }
+        else if (isRecord(safeResponse) && typeof safeResponse.success === 'boolean') {
+            wrapped.success = Boolean(safeResponse.success);
+        }
+        if (structuredPayload !== undefined) {
+            try {
+                wrapped.structuredContent = structuredPayload && typeof structuredPayload === 'object'
+                    ? cleanObject(structuredPayload)
+                    : structuredPayload;
+            }
+            catch {
+                wrapped.structuredContent = structuredPayload;
+            }
+        }
+        else if (safeResponse && typeof safeResponse === 'object') {
+            try {
+                wrapped.structuredContent = cleanObject(safeResponse);
+            }
+            catch {
+                wrapped.structuredContent = safeResponse;
+            }
+        }
+        if (hasExplicitFailurePayload(wrapped.structuredContent)) {
+            wrapped.isError = true;
+        }
+        if (!validation.valid) {
+            wrapped._validation = { valid: false, errors: validation.errors };
+        }
+        const imageContent = buildImageContent(wrapped.structuredContent ?? structuredPayload ?? safeResponse);
+        if (imageContent) {
+            wrapped.content.push(imageContent);
+        }
+        const success = wrapped.success;
+        if (typeof success === 'boolean' && success === false) {
+            wrapped.isError = true;
+        }
+        return wrapped;
+    }
+    getStats() {
+        return {
+            totalSchemas: this.validators.size,
+            tools: Array.from(this.validators.keys())
+        };
+    }
+}
+export const responseValidator = new ResponseValidator();
+//# sourceMappingURL=response-validator.js.map

package/dist/utils/responses/response-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-validator.js","sourceRoot":"","sources":["../../../src/utils/responses/response-validator.ts"],"names":[],"mappings":"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"}

package/dist/utils/responses/result-helpers.d.ts

@@ -0,0 +1,3 @@
+export declare function coerceString(value: unknown): string | undefined;
+export declare function coerceNumber(value: unknown): number | undefined;
+//# sourceMappingURL=result-helpers.d.ts.map

package/dist/utils/responses/result-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-helpers.d.ts","sourceRoot":"","sources":["../../../src/utils/responses/result-helpers.ts"],"names":[],"mappings":"AACA,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAM/D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAa/D"}

package/dist/utils/responses/result-helpers.js

@@ -0,0 +1,20 @@
+export function coerceString(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    return undefined;
+}
+export function coerceNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=result-helpers.js.map

package/dist/utils/responses/result-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-helpers.js","sourceRoot":"","sources":["../../../src/utils/responses/result-helpers.ts"],"names":[],"mappings":"AACA,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/utils/serialization/ordering.d.ts

@@ -0,0 +1,9 @@
+export declare function compareAscii(left: string, right: string): number;
+export declare function compareById<T extends {
+    readonly id: string;
+}>(left: T, right: T): number;
+export declare function sortById<T extends {
+    readonly id: string;
+}>(items: readonly T[]): T[];
+export declare function compareEntryKey(left: readonly [string, unknown], right: readonly [string, unknown]): number;
+//# sourceMappingURL=ordering.d.ts.map

package/dist/utils/serialization/ordering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ordering.d.ts","sourceRoot":"","sources":["../../../src/utils/serialization/ordering.ts"],"names":[],"mappings":"AAcA,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhE;AAGD,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAExF;AAGD,wBAAgB,QAAQ,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAEpF;AAGD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAER"}

package/dist/utils/serialization/ordering.js

@@ -0,0 +1,17 @@
+export function compareAscii(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+export function compareById(left, right) {
+    return compareAscii(left.id, right.id);
+}
+export function sortById(items) {
+    return [...items].sort(compareById);
+}
+export function compareEntryKey(left, right) {
+    return compareAscii(left[0], right[0]);
+}
+//# sourceMappingURL=ordering.js.map

package/dist/utils/serialization/ordering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ordering.js","sourceRoot":"","sources":["../../../src/utils/serialization/ordering.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,KAAa;IACtD,IAAI,IAAI,GAAG,KAAK;QAAE,OAAO,CAAC,CAAC,CAAC;IAC5B,IAAI,IAAI,GAAG,KAAK;QAAE,OAAO,CAAC,CAAC;IAC3B,OAAO,CAAC,CAAC;AACX,CAAC;AAGD,MAAM,UAAU,WAAW,CAAoC,IAAO,EAAE,KAAQ;IAC9E,OAAO,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC;AAGD,MAAM,UAAU,QAAQ,CAAoC,KAAmB;IAC7E,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AACtC,CAAC;AAGD,MAAM,UAAU,eAAe,CAC7B,IAAgC,EAChC,KAAiC;IAEjC,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC"}

package/dist/utils/serialization/safe-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-json.d.ts","sourceRoot":"","sources":["../../../src/utils/serialization/safe-json.ts"],"names":[],"mappings":"AAWA,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,GAAE,MAAW,GAAG,CAAC,CA6DzE"}

package/dist/utils/serialization/safe-json.js

@@ -0,0 +1,51 @@
+import { Logger } from '../logging/logger.js';
+const log = new Logger('safe-json');
+export function cleanObject(obj, maxDepth = 10) {
+    const activePath = new WeakSet();
+    const depthLimit = Number.isInteger(maxDepth) && maxDepth >= 0 ? maxDepth : 10;
+    function clean(value, depth, path = 'root') {
+        if (depth > depthLimit) {
+            return '[Max depth reached]';
+        }
+        if (value === null || value === undefined) {
+            return value;
+        }
+        if (typeof value !== 'object') {
+            if (typeof value === 'function' || typeof value === 'symbol') {
+                return undefined;
+            }
+            if (typeof value === 'bigint') {
+                return value.toString();
+            }
+            return value;
+        }
+        if (activePath.has(value)) {
+            return '[Circular Reference]';
+        }
+        activePath.add(value);
+        try {
+            if (Array.isArray(value)) {
+                return value.map((item, index) => clean(item, depth + 1, `${path}[${index}]`));
+            }
+            const cleaned = {};
+            const keys = Object.keys(value);
+            for (const key of keys) {
+                try {
+                    const cleanedValue = clean(value[key], depth + 1, `${path}.${key}`);
+                    if (cleanedValue !== undefined) {
+                        cleaned[key] = cleanedValue;
+                    }
+                }
+                catch (e) {
+                    log.error(`Error cleaning property ${path}.${key}`, e);
+                }
+            }
+            return cleaned;
+        }
+        finally {
+            activePath.delete(value);
+        }
+    }
+    return clean(obj, 0);
+}
+//# sourceMappingURL=safe-json.js.map

package/dist/utils/serialization/safe-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-json.js","sourceRoot":"","sources":["../../../src/utils/serialization/safe-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC;AAQpC,MAAM,UAAU,WAAW,CAAc,GAAM,EAAE,WAAmB,EAAE;IACpE,MAAM,UAAU,GAAG,IAAI,OAAO,EAAU,CAAC;IACzC,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAE/E,SAAS,KAAK,CAAC,KAAc,EAAE,KAAa,EAAE,OAAe,MAAM;QAEjE,IAAI,KAAK,GAAG,UAAU,EAAE,CAAC;YACvB,OAAO,qBAAqB,CAAC;QAC/B,CAAC;QAED,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC1C,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,OAAO,KAAK,KAAK,UAAU,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC7D,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC1B,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAKD,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,sBAAsB,CAAC;QAChC,CAAC;QAED,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAEtB,IAAI,CAAC;YACH,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;YACjF,CAAC;YAED,MAAM,OAAO,GAA4B,EAAE,CAAC;YAG5C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC;YAC1C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,IAAI,CAAC;oBACH,MAAM,YAAY,GAAG,KAAK,CAAE,KAAiC,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC;oBACjG,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;wBAC/B,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC;oBAC9B,CAAC;gBACH,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBAEX,GAAG,CAAC,KAAK,CAAC,2BAA2B,IAAI,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;gBACzD,CAAC;YACH,CAAC;YAED,OAAO,OAAO,CAAC;QACjB,CAAC;gBAAS,CAAC;YACT,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,GAAG,EAAE,CAAC,CAAM,CAAC;AAC5B,CAAC"}

package/dist/utils/validation/type-coercion.d.ts

@@ -0,0 +1,23 @@
+export declare function toNumber(val: unknown): number | undefined;
+export declare function toBoolean(val: unknown): boolean | undefined;
+export declare function toString(val: unknown): string | undefined;
+export declare function toVec3Array(v: unknown): [number, number, number] | undefined;
+export declare function toRotArray(r: unknown): [number, number, number] | undefined;
+export declare function toColor3(val: unknown): [number, number, number] | undefined;
+export declare function toLocationObj(val: unknown): {
+    x: number;
+    y: number;
+    z: number;
+} | undefined;
+export declare function toRotationObj(val: unknown): {
+    pitch: number;
+    yaw: number;
+    roll: number;
+} | undefined;
+export declare function validateAudioParams(volume?: number, pitch?: number): {
+    volume: number;
+    pitch: number;
+};
+export declare function normalizeName(value: unknown, defaultName?: string, prefix?: string): string;
+export declare function toFiniteNumber(raw: unknown): number | undefined;
+//# sourceMappingURL=type-coercion.d.ts.map

package/dist/utils/validation/type-coercion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-coercion.d.ts","sourceRoot":"","sources":["../../../src/utils/validation/type-coercion.ts"],"names":[],"mappings":"AAyBA,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIzD;AAMD,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAG3D;AAMD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGzD;AAUD,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAQ5E;AAMD,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAQ3E;AAMD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAO3E;AAMD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAkB3F;AAMD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAkBpG;AAUD,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAOtG;AAMD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,GAAE,MAAiB,GAAG,MAAM,CAUrG;AAMD,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAS/D"}

package/dist/utils/validation/type-coercion.js

@@ -0,0 +1,128 @@
+function finiteNumberOrDefault(value, fallback) {
+    if (value === undefined || value === null)
+        return fallback;
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : fallback;
+}
+export function toNumber(val) {
+    if (val === undefined || val === null)
+        return undefined;
+    const n = Number(val);
+    return Number.isFinite(n) ? n : undefined;
+}
+export function toBoolean(val) {
+    if (val === undefined || val === null)
+        return undefined;
+    return Boolean(val);
+}
+export function toString(val) {
+    if (val === undefined || val === null)
+        return undefined;
+    return String(val);
+}
+export function toVec3Array(v) {
+    if (!v || typeof v !== 'object')
+        return undefined;
+    const vec = v;
+    const x = Number(vec.x);
+    const y = Number(vec.y);
+    const z = Number(vec.z);
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+        return undefined;
+    return [x, y, z];
+}
+export function toRotArray(r) {
+    if (!r || typeof r !== 'object')
+        return undefined;
+    const rot = r;
+    const pitch = Number(rot.pitch);
+    const yaw = Number(rot.yaw);
+    const roll = Number(rot.roll);
+    if (!Number.isFinite(pitch) || !Number.isFinite(yaw) || !Number.isFinite(roll))
+        return undefined;
+    return [pitch, yaw, roll];
+}
+export function toColor3(val) {
+    if (!Array.isArray(val) || val.length < 3)
+        return undefined;
+    return [
+        finiteNumberOrDefault(val[0], 0),
+        finiteNumberOrDefault(val[1], 0),
+        finiteNumberOrDefault(val[2], 0)
+    ];
+}
+export function toLocationObj(val) {
+    if (!val)
+        return undefined;
+    if (Array.isArray(val) && val.length >= 3) {
+        return {
+            x: finiteNumberOrDefault(val[0], 0),
+            y: finiteNumberOrDefault(val[1], 0),
+            z: finiteNumberOrDefault(val[2], 0)
+        };
+    }
+    if (typeof val === 'object') {
+        const obj = val;
+        return {
+            x: finiteNumberOrDefault(obj.x, 0),
+            y: finiteNumberOrDefault(obj.y, 0),
+            z: finiteNumberOrDefault(obj.z, 0)
+        };
+    }
+    return undefined;
+}
+export function toRotationObj(val) {
+    if (!val)
+        return undefined;
+    if (Array.isArray(val) && val.length >= 3) {
+        return {
+            pitch: finiteNumberOrDefault(val[0], 0),
+            yaw: finiteNumberOrDefault(val[1], 0),
+            roll: finiteNumberOrDefault(val[2], 0)
+        };
+    }
+    if (typeof val === 'object') {
+        const obj = val;
+        return {
+            pitch: finiteNumberOrDefault(obj.pitch, 0),
+            yaw: finiteNumberOrDefault(obj.yaw, 0),
+            roll: finiteNumberOrDefault(obj.roll, 0)
+        };
+    }
+    return undefined;
+}
+export function validateAudioParams(volume, pitch) {
+    const v = finiteNumberOrDefault(volume, 1.0);
+    const p = finiteNumberOrDefault(pitch, 1.0);
+    return {
+        volume: Math.max(0.0, Math.min(v, 4.0)),
+        pitch: Math.max(0.01, Math.min(p, 4.0))
+    };
+}
+export function normalizeName(value, defaultName, prefix = 'Object') {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
+    if (typeof defaultName === 'string') {
+        const trimmedDefault = defaultName.trim();
+        if (trimmedDefault.length > 0)
+            return trimmedDefault;
+    }
+    return `${prefix}_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+}
+export function toFiniteNumber(raw) {
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            return undefined;
+        const parsed = Number(trimmed);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+//# sourceMappingURL=type-coercion.js.map

package/dist/utils/validation/type-coercion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-coercion.js","sourceRoot":"","sources":["../../../src/utils/validation/type-coercion.ts"],"names":[],"mappings":"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"}

package/dist/utils/validation/type-guards.d.ts

@@ -0,0 +1,3 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function hasOwn(target: object, key: string): boolean;
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/utils/validation/type-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../../../src/utils/validation/type-guards.ts"],"names":[],"mappings":"AAAA,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAOD,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3D"}

package/dist/utils/validation/type-guards.js

@@ -0,0 +1,7 @@
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function hasOwn(target, key) {
+    return Object.prototype.hasOwnProperty.call(target, key);
+}
+//# sourceMappingURL=type-guards.js.map

package/dist/utils/validation/type-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.js","sourceRoot":"","sources":["../../../src/utils/validation/type-guards.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAOD,MAAM,UAAU,MAAM,CAAC,MAAc,EAAE,GAAW;IAChD,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC3D,CAAC"}

package/dist/utils/validation/validation.d.ts

@@ -0,0 +1,4 @@
+export declare function sanitizeCommandArgument(arg: string): string;
+export declare function sanitizeAssetName(name: string): string;
+export declare function normalizeAndSanitizeAssetPath(path: string): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/utils/validation/validation.ts"],"names":[],"mappings":"AAoDA,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAuB3D;AAOD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAyCtD;AAWD,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiDlE"}