xypriss 9.11.13 → 9.12.0

package/dist/src/utils/ConfigSyntaxParser.js

@@ -0,0 +1,240 @@
+/**
+ * **Config Syntax Parser**
+ *
+ * Handles resolution of dynamic references in configuration files:
+ * - `&(env).KEY`   : Environment variables
+ * - `&(pkg).path`  : package.json properties (dot-notation)
+ * - `&(this).KEY`  : Properties from the currently parsed object
+ * - `&(const).KEY` : Build-time constants injected at construction
+ * - `&(date).FMT`  : Current date/time helpers (ISO, YEAR, MONTH, DAY, TS)
+ * - `&(file).path` : Synchronous file content (use for secrets, certs, etc.)
+ */
+import { getSysApi } from "../plugins/const/getSysApi";
+// Valid reference types — extend here when adding new syntax.
+const VALID_TYPES = new Set(["env", "pkg", "this", "date", "file"]);
+// Date format tokens supported by &(date).TOKEN
+const DATE_TOKENS = {
+    ISO: () => new Date().toISOString(),
+    YEAR: () => String(new Date().getFullYear()),
+    MONTH: () => String(new Date().getMonth() + 1).padStart(2, "0"),
+    DAY: () => String(new Date().getDate()).padStart(2, "0"),
+    TS: () => String(Date.now()),
+    TIME: () => new Date().toTimeString().split(" ")[0], // HH:MM:SS
+};
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+export class ConfigSyntaxParser {
+    constructor(packageJson = null, envProvider = null, constants = {}, options = {}) {
+        this.packageJson = packageJson;
+        this.envProvider = envProvider;
+        this.constants = constants;
+        // LRU-style cache for getDeepValue on the same object reference
+        this.deepValueCache = new WeakMap();
+        this.fileBasePath = options.fileBasePath ?? process.cwd();
+        this.maxPasses = options.maxPasses ?? 20;
+    }
+    // -------------------------------------------------------------------------
+    // Public API — signatures intentionally unchanged
+    // -------------------------------------------------------------------------
+    /**
+     * Resolves all dynamic references in a configuration object or string.
+     * Non-string/array/object values are returned as-is.
+     */
+    resolve(obj, rootObj) {
+        if (rootObj === undefined)
+            rootObj = obj;
+        if (typeof obj === "string")
+            return this.resolveString(obj, rootObj);
+        if (Array.isArray(obj))
+            return obj.map((item) => this.resolve(item, rootObj));
+        if (typeof obj === "object" && obj !== null) {
+            const resolved = {};
+            for (const key of Object.keys(obj)) {
+                const resolvedKey = String(this.resolve(key, rootObj));
+                resolved[resolvedKey] = this.resolve(obj[key], rootObj);
+            }
+            return resolved;
+        }
+        return obj; // number, boolean, null, undefined — pass through untouched
+    }
+    // -------------------------------------------------------------------------
+    // Core resolution
+    // -------------------------------------------------------------------------
+    /**
+     * Resolves dynamic references in a string, supporting chained || fallbacks.
+     */
+    resolveString(value, rootObj) {
+        // Validate before any resolution to catch syntax errors even in unused fallbacks
+        this.validateSyntax(value);
+        // Matches: &(type).key  ||  &(type).key  ||  literal-fallback
+        // Group 1 — type
+        // Group 2 — key/path
+        // Group 3 — remainder of the || chain
+        // Separate simple types (env, const, date) from complex types (pkg, this, file)
+        // to prevent over-matching separators like '.' or '-' in strings.
+        const chainRegex = /&\((env|const|date)\)\.([\w\d_$]+)((?:\s*\|\|\s*(?:&\((?:[\w]+)\)\.[\w\d_./$]+(?:-[\w\d_./$]+)*|[^|,]+))*)|&\((pkg|this|file)\)\.([\w\d_/$][\w\d_./$]*(?:-[\w\d_./$]+)*)((?:\s*\|\|\s*(?:&\((?:[\w]+)\)\.[\w\d_./$]+(?:-[\w\d_./$]+)*|[^|,]+))*)/g;
+        let result = value;
+        let passes = 0;
+        while (passes++ < this.maxPasses) {
+            const prev = result;
+            // Reset regex before each pass (global flag keeps lastIndex)
+            chainRegex.lastIndex = 0;
+            result = result.replace(chainRegex, (_match, type1, key1, chain1, type2, key2, chain2) => {
+                const type = type1 || type2;
+                const key = key1 || key2;
+                const chain = chain1 || chain2;
+                const val = this.getValue(type, key, rootObj);
+                if (val !== undefined)
+                    return val;
+                if (chain) {
+                    // Strip leading " || " and let the next pass handle it
+                    return chain.replace(/^\s*\|\|\s*/, "");
+                }
+                throw new Error(this.buildMissingError(type, key));
+            });
+            if (result === prev)
+                break;
+        }
+        if (passes > this.maxPasses) {
+            throw new Error(`ESYNC: Resolution did not stabilise after ${this.maxPasses} passes in "${value}". ` +
+                `Possible circular reference.`);
+        }
+        this.validateSyntax(result);
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Value retrieval
+    // -------------------------------------------------------------------------
+    /**
+     * Dispatches value retrieval to the appropriate provider.
+     */
+    getValue(type, key, rootObj) {
+        switch (type) {
+            case "env":
+                return this.getEnv(key);
+            case "pkg":
+                return this.getPkg(key);
+            case "this":
+                return this.getThis(key, rootObj);
+            case "date":
+                return this.getDate(key);
+            case "file":
+                return this.getFile(key);
+            default:
+                return undefined; // validateSyntax will catch this
+        }
+    }
+    getEnv(key) {
+        return this.envProvider?.has(key)
+            ? this.envProvider.get(key)
+            : undefined;
+    }
+    getPkg(key) {
+        if (!this.packageJson)
+            return undefined;
+        const val = this.getDeepValue(this.packageJson, key);
+        return val !== undefined ? String(val) : undefined;
+    }
+    getThis(key, rootObj) {
+        if (rootObj === null || typeof rootObj !== "object")
+            return undefined;
+        const val = this.getDeepValue(rootObj, key);
+        return val !== undefined ? String(val) : undefined;
+    }
+    getDate(token) {
+        const upper = token.toUpperCase();
+        return DATE_TOKENS[upper]?.();
+        // Unknown date tokens fall through to the error handler
+    }
+    getFile(filePath) {
+        try {
+            const sys = getSysApi();
+            // In XyPriss config, a leading / is often intended as project-root relative
+            // especially when the separator dot consumes the '.' of './path'
+            const cleanPath = filePath.startsWith("/")
+                ? filePath.substring(1)
+                : filePath;
+            const resolved = sys.path.isAbsolute(cleanPath)
+                ? cleanPath
+                : sys.path.resolve(this.fileBasePath, cleanPath);
+            return sys.fs.readSync(resolved).trim();
+        }
+        catch {
+            return undefined; // triggers fallback chain or missing-key error
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Deep value with caching
+    // -------------------------------------------------------------------------
+    /**
+     * Retrieves a value from a nested object using dot notation.
+     * Results are cached per object reference to avoid repeated traversal.
+     */
+    getDeepValue(obj, path) {
+        // Check cache
+        let pathMap = this.deepValueCache.get(obj);
+        if (pathMap?.has(path))
+            return pathMap.get(path);
+        const parts = path.split(".");
+        let current = obj;
+        for (const part of parts) {
+            if (current === null || typeof current !== "object") {
+                current = undefined;
+                break;
+            }
+            current = current[part];
+        }
+        // Store in cache
+        if (!pathMap) {
+            pathMap = new Map();
+            this.deepValueCache.set(obj, pathMap);
+        }
+        pathMap.set(path, current);
+        return current;
+    }
+    // -------------------------------------------------------------------------
+    // Validation
+    // -------------------------------------------------------------------------
+    /**
+     * Validates that no unresolved or malformed markers remain in the string.
+     */
+    validateSyntax(value) {
+        if (!/&\(/.test(value))
+            return;
+        const malformedRegex = /&\((env|const|date)\)\.([\w\d_$]+)?|&\((pkg|this|file)\)\.([\w\d_/$][\w\d_./$]*(?:-[\w\d_./$]+)*)?/g;
+        let match;
+        while ((match = malformedRegex.exec(value)) !== null) {
+            const [full, type1, key1, type2, key2] = match;
+            const type = type1 || type2;
+            const key = key1 || key2;
+            if (!type) {
+                // This shouldn't happen with the current regex, but safety first
+                throw new Error(`ESYNC: Invalid or malformed injection syntax detected in "${full}".`);
+            }
+            if (!key) {
+                throw new Error(`ESYNC: Malformed syntax "${full}". Missing key or property path.`);
+            }
+        }
+        // Catch any `&(` that didn't even loosely match the malformedRegex
+        const stripped = value.replace(malformedRegex, "");
+        if (/&\(/.test(stripped)) {
+            throw new Error(`ESYNC: Invalid or malformed injection syntax detected in "${value}".`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Error formatting
+    // -------------------------------------------------------------------------
+    buildMissingError(type, key) {
+        const descriptions = {
+            env: `Environment variable "${key}"`,
+            pkg: `Property "${key}" in package.json`,
+            this: `Property "${key}" in current object`,
+            date: `Date token "${key}" (valid: ${Object.keys(DATE_TOKENS).join(", ")})`,
+            file: `File "${key}"`,
+        };
+        const desc = descriptions[type] ?? `Reference "${key}" (type: ${type})`;
+        return `EDYNC: ${desc} not found or could not be resolved.`;
+    }
+}
+//# sourceMappingURL=ConfigSyntaxParser.js.map

package/dist/src/utils/ConfigSyntaxParser.js.map

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

package/dist/src/utils/DotEnvLoader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * **DotEnvLoader**
+ *
+ * A lightweight, zero-dependency .env file parser and loader.
+ * Inspired by the standard dotenv logic but built specifically for XyPriss.
+ */
+export declare class DotEnvLoader {
+    private static readonly LINE;
+    /**
+     * Parses a string or buffer containing .env file content.
+     * @param src Content of the .env file.
+     * @returns Object with key-value pairs.
+     */
+    static parse(src: string | Buffer): Record<string, string>;
+    /**
+     * Loads .env files into an object (usually process.env).
+     * @param options Configuration for loading.
+     * @returns The parsed object.
+     */
+    static load(options?: {
+        path?: string | string[];
+        override?: boolean;
+    }): Record<string, string>;
+}
+//# sourceMappingURL=DotEnvLoader.d.ts.map

package/dist/src/utils/DotEnvLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DotEnvLoader.d.ts","sourceRoot":"","sources":["../../../src/utils/DotEnvLoader.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CACuH;IAEnJ;;;;OAIG;WACW,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IA6BjE;;;;OAIG;WACW,IAAI,CACd,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GAC/D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CA4B5B"}

package/dist/src/utils/DotEnvLoader.js

@@ -0,0 +1,69 @@
+import fs from "fs";
+import path from "path";
+/**
+ * **DotEnvLoader**
+ *
+ * A lightweight, zero-dependency .env file parser and loader.
+ * Inspired by the standard dotenv logic but built specifically for XyPriss.
+ */
+export class DotEnvLoader {
+    /**
+     * Parses a string or buffer containing .env file content.
+     * @param src Content of the .env file.
+     * @returns Object with key-value pairs.
+     */
+    static parse(src) {
+        const obj = {};
+        let content = src.toString();
+        content = content.replace(/\r\n?/gm, "\n");
+        let match;
+        // Reset lastIndex for the global regex
+        this.LINE.lastIndex = 0;
+        while ((match = this.LINE.exec(content)) !== null) {
+            const key = match[1];
+            let value = (match[2] || "").trim();
+            // Handle quoted values
+            const maybeQuote = value[0];
+            value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
+            // Handle escaped characters in double quotes
+            if (maybeQuote === '"') {
+                value = value.replace(/\\n/g, "\n");
+                value = value.replace(/\\r/g, "\r");
+            }
+            obj[key] = value;
+        }
+        return obj;
+    }
+    /**
+     * Loads .env files into an object (usually process.env).
+     * @param options Configuration for loading.
+     * @returns The parsed object.
+     */
+    static load(options = {}) {
+        const paths = Array.isArray(options.path)
+            ? options.path
+            : [options.path || path.resolve(process.cwd(), ".env")];
+        const override = options.override ?? false;
+        const parsedAll = {};
+        for (const envPath of paths) {
+            try {
+                if (fs.existsSync(envPath)) {
+                    const content = fs.readFileSync(envPath);
+                    const parsed = this.parse(content);
+                    for (const [key, value] of Object.entries(parsed)) {
+                        if (override || process.env[key] === undefined) {
+                            process.env[key] = value;
+                        }
+                        parsedAll[key] = value;
+                    }
+                }
+            }
+            catch (err) {
+                // Silently ignore or log if debug is enabled
+            }
+        }
+        return parsedAll;
+    }
+}
+DotEnvLoader.LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/gm;
+//# sourceMappingURL=DotEnvLoader.js.map

package/dist/src/utils/DotEnvLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DotEnvLoader.js","sourceRoot":"","sources":["../../../src/utils/DotEnvLoader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IAIrB;;;;OAIG;IACI,MAAM,CAAC,KAAK,CAAC,GAAoB;QACpC,MAAM,GAAG,GAA2B,EAAE,CAAC;QACvC,IAAI,OAAO,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QAC7B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAE3C,IAAI,KAAK,CAAC;QACV,uCAAuC;QACvC,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QAExB,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACrB,IAAI,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAEpC,uBAAuB;YACvB,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YAC5B,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,wBAAwB,EAAE,IAAI,CAAC,CAAC;YAEtD,6CAA6C;YAC7C,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;gBACrB,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACpC,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACxC,CAAC;YAED,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACrB,CAAC;QAED,OAAO,GAAG,CAAC;IACf,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,IAAI,CACd,UAA4D,EAAE;QAE9D,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC;YACrC,CAAC,CAAC,OAAO,CAAC,IAAI;YACd,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;QAE5D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;QAC3C,MAAM,SAAS,GAA2B,EAAE,CAAC;QAE7C,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACD,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;oBACzB,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;oBACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;oBAEnC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;wBAChD,IAAI,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;4BAC7C,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;wBAC7B,CAAC;wBACD,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;oBAC3B,CAAC;gBACL,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,6CAA6C;YACjD,CAAC;QACL,CAAC;QAED,OAAO,SAAS,CAAC;IACrB,CAAC;;AAvEuB,iBAAI,GACxB,8IAA8I,CAAC"}

package/dist/src/utils/JsonUtils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * JSON Utility Library
+ *
+ * Implements robust comment stripping and safe parsing for JSONC/JSON configuration files.
+ */
+export declare class JsonUtils {
+    /**
+     * Strip single-line (//) and multi-line (/*) comments from a string content,
+     * while retaining strings and resolving trailing commas for JSON-compatibility.
+     *
+     * @param content - Raw JSONC content.
+     * @returns Sanitized standard JSON string.
+     */
+    static stripComments(content: string): string;
+    /**
+     * Safely parse comments-enabled JSONC strings into JavaScript objects.
+     *
+     * @param content - Raw JSONC string.
+     * @returns Parsed object.
+     */
+    static parse<T = any>(content: string): T;
+}
+//# sourceMappingURL=JsonUtils.d.ts.map

package/dist/src/utils/JsonUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/JsonUtils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,SAAS;IAClB;;;;;;OAMG;WACW,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAWpD;;;;;OAKG;WACW,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC;CAInD"}

package/dist/src/utils/JsonUtils.js

@@ -0,0 +1,29 @@
+/**
+ * JSON Utility Library
+ *
+ * Implements robust comment stripping and safe parsing for JSONC/JSON configuration files.
+ */
+export class JsonUtils {
+    /**
+     * Strip single-line (//) and multi-line (/*) comments from a string content,
+     * while retaining strings and resolving trailing commas for JSON-compatibility.
+     *
+     * @param content - Raw JSONC content.
+     * @returns Sanitized standard JSON string.
+     */
+    static stripComments(content) {
+        const noComments = content.replace(/("(?:[^"\\]|\\.)*")|\/\/.*|\/\*[\s\S]*?\*\//g, (match, group1) => (group1 ? group1 : ""));
+        return noComments.replace(/("(?:[^"\\]|\\.)*")|,\s*([}\]])/g, (match, group1, group2) => (group1 ? group1 : group2));
+    }
+    /**
+     * Safely parse comments-enabled JSONC strings into JavaScript objects.
+     *
+     * @param content - Raw JSONC string.
+     * @returns Parsed object.
+     */
+    static parse(content) {
+        const clean = this.stripComments(content);
+        return JSON.parse(clean);
+    }
+}
+//# sourceMappingURL=JsonUtils.js.map

package/dist/src/utils/JsonUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonUtils.js","sourceRoot":"","sources":["../../../src/utils/JsonUtils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,SAAS;IAClB;;;;;;OAMG;IACI,MAAM,CAAC,aAAa,CAAC,OAAe;QACvC,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAC9B,8CAA8C,EAC9C,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAC5C,CAAC;QACF,OAAO,UAAU,CAAC,OAAO,CACrB,kCAAkC,EAClC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CACxD,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAU,OAAe;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;CACJ"}

package/dist/src/utils/ProjectDiscovery.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Checks if a directory is a "Real Project" root based on hierarchical criteria.
+ * Criteria:
+ * 1. (package.json + node_modules) -> Strong baseline
+ * 2. (package.json + src + tsconfig.json) -> High priority
+ */
+export declare function isProjectRoot(dir: string): boolean;
+/**
+ * Identifies the project root for a given caller path by traversing up the filesystem.
+ */
+export declare function identifyProjectRoot(filePath: string): string | undefined;
+export declare function setRootInterceptor(interceptor: (callerRoot: string) => string | undefined): void;
+/**
+ * Retrieves the project root of the code currently executing by analyzing the stack trace.
+ */
+export declare function getCallerProjectRoot(): string | undefined;
+/**
+ * Checks if a given file path belongs to the deep engine core.
+ * These files are skipped during stack analysis to find the user/plugin caller.
+ */
+export declare function isEngineCorePath(filePath: string): boolean;
+/**
+ * Checks if a given file path belongs directly to the XyPriss Core Engine
+ * or if it comes from an external plugin / user space.
+ * This is used for SECURITY authorization.
+ */
+export declare function isCoreFrameworkPath(filePath: string): boolean;
+/**
+ * Validates a call stack to determine whether the execution trace originated
+ * safely from within the core framework, dropping unauthorized usage.
+ */
+export declare function isCoreStack(stack: string): boolean;
+/**
+ * Checks if a given file path belongs to a trusted dependency (root node_modules).
+ * Trusted dependencies are those installed in the main project's node_modules
+ * but NOT inside a plugin directory.
+ */
+export declare function isTrustedDependencyPath(filePath: string): boolean;
+/**
+ * Checks if a given file path belongs to a plugin (resides in /mods/).
+ */
+export declare function isPluginPath(filePath: string): boolean;
+/**
+ * Checks if a given file path belongs to a test directory (e.g., /.private/).
+ */
+export declare function isTestPath(filePath: string): boolean;
+/**
+ * Loads and cleans a XyPriss configuration file (JSON or JSONC).
+ * Removes comments and trailing commas to ensure compatibility with standard JSON.parse.
+ */
+export declare function loadXyConfig(projectRoot: string): any | null;
+/**
+ * Verifies if a given directory contains a valid XyPriss plugin contract.
+ * Required: xypriss.config.json(c) with the plugin's namespace under '$internal'
+ */
+export declare function verifyPluginContract(pluginRoot: string, pluginName: string): boolean;
+/**
+ * Retrieves the plugin configuration if it exists and is valid.
+ */
+export declare function getPluginConfig(pluginRoot: string): any | null;
+//# sourceMappingURL=ProjectDiscovery.d.ts.map

package/dist/src/utils/ProjectDiscovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectDiscovery.d.ts","sourceRoot":"","sources":["../../../src/utils/ProjectDiscovery.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA6BlD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAuBxE;AAGD,wBAAgB,kBAAkB,CAC9B,WAAW,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,QAG1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAuDzD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAiB1D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAe7D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAkElD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOjE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGtD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGpD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CA6C5D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAChC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACnB,OAAO,CAUT;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAE9D"}