minovative-mind-cli 2.11.3 → 2.11.5

package/dist/services/orchestration/scopedTools.js

@@ -1,14 +1,34 @@
 import path from 'path';
 import { executeTool, getToolDeclarations as getBaseToolDeclarations } from '../agent-tools.js';
 import { MessageBus } from './messageBus.js';
+import { resolveAndValidateMultiWorkspacePath } from '../../utils/pathSecurity.js';
 import { debugLog } from '../../utils/logger.js';
 /**
- * Extended tool declarations for sub-agents, merging the standard tools
- * with orchestration-specific ones (e.g., post_message, read_messages).
+ * Resolves a file path to its canonical absolute path for lock registry keying,
+ * accounting for multi-workspace alias resolution and default primary sub-path auto-focusing.
+ *
+ * @param workspaceRoot - The base primary workspace root directory
+ * @param filePath - The relative or aliased file path
+ * @param options - Optional sub-path override configuration
+ * @returns Absolute canonical file path
+ */
+export function resolveCanonicalLockPath(workspaceRoot, filePath, options) {
+    try {
+        const resolved = resolveAndValidateMultiWorkspacePath(workspaceRoot, filePath, options);
+        return resolved.absolutePath;
+    }
+    catch {
+        return path.isAbsolute(filePath) ? filePath : path.resolve(workspaceRoot, filePath);
+    }
+}
+/**
+ * Returns Gemini tool declarations available to sub-agents during orchestration.
+ * In addition to standard agent tools (read/write/search/command/etc.), includes
+ * inter-agent communication tools (post_message, read_messages).
  */
 export function getScopedToolDeclarations() {
-    return [
-        ...getBaseToolDeclarations({ isExecutionAgent: true }),
+    const baseTools = getBaseToolDeclarations({ isExecutionAgent: true });
+    const orchestrationTools = [
         {
             name: 'post_message',
             description: 'Post a semantic message to the orchestration bus to coordinate with other agents.',
@@ -23,15 +43,15 @@ export function getScopedToolDeclarations() {
                         type: 'STRING',
                         description: 'The semantic intent or message content',
                     },
-                    toAgent: {
-                        type: 'STRING',
-                        description: 'Optional target agent ID (required for "request")',
-                    },
                     affectedFiles: {
                         type: 'ARRAY',
                         items: { type: 'STRING' },
                         description: 'Files involved (required for "discovery")',
                     },
+                    toAgent: {
+                        type: 'STRING',
+                        description: 'Optional target agent ID (required for "request")',
+                    },
                 },
                 required: ['type', 'content'],
             },
@@ -45,16 +65,23 @@ export function getScopedToolDeclarations() {
             },
         },
     ];
+    return [...baseTools, ...orchestrationTools];
 }
 /**
- * Wraps the global executeTool to provide sub-agent context.
+ * Executes a tool within the sub-agent execution boundary.
+ * Handles concurrency locking for file-mutating operations, sends progress
+ * notifications to the orchestrator, and logs activity to the message bus.
  *
- * 1. Captures tool execution into the MessageBus (Layer 1: zero-cost logs).
- * 2. Implements FileLocks for write/modify operations to prevent race conditions.
- * 3. Handles `post_message` and `read_messages` directly.
- * 4. Calls a heartbeat callback to notify the orchestrator this agent is alive.
+ * @param name - Tool function name
+ * @param args - Tool arguments object
+ * @param workspaceRoot - Primary workspace root directory
+ * @param agentId - Unique ID of the executing agent
+ * @param bus - Shared message bus instance
+ * @param locks - Shared file lock registry instance
+ * @param onProgress - Callback to notify parent of sub-agent progress
+ * @param options - Optional sub-path auto-focus and override configuration
  */
-export async function executeScopedTool(name, args, workspaceRoot, agentId, bus, locks, onProgress) {
+export async function executeScopedTool(name, args, workspaceRoot, agentId, bus, locks, onProgress, options) {
     // Update heartbeat so the orchestrator knows we are making progress
     onProgress();
     const timestamp = Date.now();
@@ -97,10 +124,25 @@ export async function executeScopedTool(name, args, workspaceRoot, agentId, bus,
         let lockedFile = null;
         let diffContext = null;
         if (name === 'write_file' || name === 'modify_file' || name === 'delete_file') {
-            lockedFile = args.filePath;
-            if (lockedFile) {
-                debugLog(`Agent "${agentId}" requesting lock for "${lockedFile}" (tool: ${name})`);
-                onProgress(`waiting for lock on ${lockedFile.split('/').pop()}...`);
+            const rawPath = args.filePath;
+            if (rawPath) {
+                lockedFile = resolveCanonicalLockPath(workspaceRoot, rawPath, options);
+                debugLog(`Agent "${agentId}" requesting lock for "${lockedFile}" (raw: "${rawPath}", tool: ${name})`);
+                onProgress(`waiting for lock on ${path.basename(lockedFile)}...`);
+                const lockRes = await locks.acquire(lockedFile, agentId);
+                onProgress(`acquired lock, executing...`);
+                diffContext = lockRes.previousDiff;
+                if (lockRes.forceReleased) {
+                    debugLog(`Agent "${agentId}" got forced lock on "${lockedFile}" (previous owner stalled)`);
+                }
+            }
+        }
+        else if (name === 'rename_file') {
+            const rawPath = args.sourcePath;
+            if (rawPath) {
+                lockedFile = resolveCanonicalLockPath(workspaceRoot, rawPath, options);
+                debugLog(`Agent "${agentId}" requesting lock for "${lockedFile}" (raw: "${rawPath}", tool: ${name})`);
+                onProgress(`waiting for lock on ${path.basename(lockedFile)}...`);
                 const lockRes = await locks.acquire(lockedFile, agentId);
                 onProgress(`acquired lock, executing...`);
                 diffContext = lockRes.previousDiff;

package/dist/services/proxyClient.js

@@ -1,4 +1,5 @@
-import { debugLog } from '../utils/logger.js';
+import { debugLog, isDebugOn } from '../utils/logger.js';
+import { GEMINI_MODELS } from '../utils/config.js';
 import { getMetricCollector } from './metrics.js';
 /**
  * ============================================================================
@@ -98,6 +99,7 @@ export class ProxyClient {
         const BASE_DELAY_MS = 2000;
         const MAX_DELAY_MS = 30000;
         let attempt = 0;
+        let activeModel = modelName;
         retryLoop: while (true) {
             if (abortSignal?.aborted) {
                 const err = new Error('Operation aborted');
@@ -111,7 +113,7 @@ export class ProxyClient {
                     'X-Firebase-Auth': `Bearer ${idToken}`,
                 },
                 body: JSON.stringify({
-                    model: modelName,
+                    model: activeModel,
                     contents,
                     tools,
                     toolConfig,
@@ -120,25 +122,39 @@ export class ProxyClient {
                 }),
                 signal: abortSignal,
             });
-            debugLog(`Proxy Request to ${modelName} complete. Status: ${response.status} ${response.statusText}`);
-            if ((response.status === 429 || response.status === 503 || response.status === 502 || response.status === 500 || response.status === 504) && attempt < MAX_RETRIES) {
-                if (abortSignal?.aborted) {
-                    const err = new Error('Operation aborted');
-                    err.name = 'AbortError';
-                    throw err;
+            debugLog(`Proxy Request to ${activeModel} complete. Status: ${response.status} ${response.statusText}`);
+            if (response.status === 429 || response.status === 503 || response.status === 502 || response.status === 500 || response.status === 504) {
+                if (attempt < MAX_RETRIES) {
+                    if (abortSignal?.aborted) {
+                        const err = new Error('Operation aborted');
+                        err.name = 'AbortError';
+                        throw err;
+                    }
+                    const exponentialDelay = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * Math.pow(2, attempt));
+                    const delayTime = Math.round(exponentialDelay * (1.0 + Math.random() * 0.5));
+                    if (isDebugOn()) {
+                        process.stdout.write('\n');
+                        console.warn(`Server error or rate limit hit (${response.status}). Retrying in ${(delayTime / 1000).toFixed(1)}s... (Attempt ${attempt + 1}/${MAX_RETRIES})`);
+                    }
+                    await delay(delayTime, abortSignal);
+                    if (abortSignal?.aborted) {
+                        const err = new Error('Operation aborted');
+                        err.name = 'AbortError';
+                        throw err;
+                    }
+                    attempt++;
+                    continue;
                 }
-                const exponentialDelay = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * Math.pow(2, attempt));
-                const delayTime = Math.round(exponentialDelay * (1.0 + Math.random() * 0.5));
-                process.stdout.write('\n');
-                console.warn(`Server error or rate limit hit (${response.status}). Retrying in ${(delayTime / 1000).toFixed(1)}s... (Attempt ${attempt + 1}/${MAX_RETRIES})`);
-                await delay(delayTime, abortSignal);
-                if (abortSignal?.aborted) {
-                    const err = new Error('Operation aborted');
-                    err.name = 'AbortError';
-                    throw err;
+                else if (activeModel !== GEMINI_MODELS.FLASH_LITE) {
+                    debugLog(`Rate limit retries exhausted (${MAX_RETRIES}/${MAX_RETRIES}) for ${activeModel}. Automatically falling back to ${GEMINI_MODELS.FLASH_LITE}...`);
+                    if (isDebugOn()) {
+                        process.stdout.write('\n');
+                        console.warn(`Rate limit retries exhausted on ${activeModel}. Automatically switching to Flash-Lite (${GEMINI_MODELS.FLASH_LITE}) to complete request...`);
+                    }
+                    activeModel = GEMINI_MODELS.FLASH_LITE;
+                    attempt = 0;
+                    continue retryLoop;
                 }
-                attempt++;
-                continue;
             }
             if (response.status === 401) {
                 let details = '';
@@ -227,8 +243,8 @@ export class ProxyClient {
                                     if (data.usage.remainingBalance !== undefined) {
                                         globalSessionAccumulatedUsage.remainingBalance = data.usage.remainingBalance;
                                     }
-                                    globalSessionAccumulatedUsage.modelsUsed[modelName] =
-                                        (globalSessionAccumulatedUsage.modelsUsed[modelName] || 0) + 1;
+                                    globalSessionAccumulatedUsage.modelsUsed[activeModel] =
+                                        (globalSessionAccumulatedUsage.modelsUsed[activeModel] || 0) + 1;
                                 }
                                 if (data.groundingMetadata) {
                                     groundingMetadata = data.groundingMetadata;
@@ -264,8 +280,10 @@ export class ProxyClient {
                     if (attempt < MAX_RETRIES) {
                         const exponentialDelay = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * Math.pow(2, attempt));
                         const delayTime = Math.round(exponentialDelay * (1.0 + Math.random() * 0.5));
-                        process.stdout.write('\n');
-                        console.warn(`Server error or rate limit hit during stream. Retrying in ${(delayTime / 1000).toFixed(1)}s... (Attempt ${attempt + 1}/${MAX_RETRIES})`);
+                        if (isDebugOn()) {
+                            process.stdout.write('\n');
+                            console.warn(`Server error or rate limit hit during stream. Retrying in ${(delayTime / 1000).toFixed(1)}s... (Attempt ${attempt + 1}/${MAX_RETRIES})`);
+                        }
                         await delay(delayTime, abortSignal);
                         if (abortSignal?.aborted) {
                             const err = new Error('Operation aborted');
@@ -275,6 +293,16 @@ export class ProxyClient {
                         attempt++;
                         continue retryLoop;
                     }
+                    else if (activeModel !== GEMINI_MODELS.FLASH_LITE) {
+                        debugLog(`Stream rate limit retries exhausted (${MAX_RETRIES}/${MAX_RETRIES}) for ${activeModel}. Automatically falling back to ${GEMINI_MODELS.FLASH_LITE}...`);
+                        if (isDebugOn()) {
+                            process.stdout.write('\n');
+                            console.warn(`Stream rate limit exhausted on ${activeModel}. Automatically switching to Flash-Lite (${GEMINI_MODELS.FLASH_LITE}) to complete request...`);
+                        }
+                        activeModel = GEMINI_MODELS.FLASH_LITE;
+                        attempt = 0;
+                        continue retryLoop;
+                    }
                 }
                 throw streamError;
             }
@@ -297,8 +325,6 @@ export class ProxyClient {
      */
     async generateViaBYOK(apiKey, modelName, contents, tools, toolConfig, systemInstruction, generationConfig, streamCallbacks, abortSignal) {
         const isStreaming = Boolean(streamCallbacks?.onChunk);
-        const endpoint = isStreaming ? 'streamGenerateContent?alt=sse&key=' : 'generateContent?key=';
-        const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(modelName)}:${endpoint}${encodeURIComponent(apiKey)}`;
         const formattedSystemInstruction = typeof systemInstruction === 'string' ? { parts: [{ text: systemInstruction }] } : systemInstruction;
         const payload = { contents };
         if (tools && tools.length > 0)
@@ -313,42 +339,58 @@ export class ProxyClient {
         const BASE_DELAY_MS = 2000;
         const MAX_DELAY_MS = 30000;
         let attempt = 0;
-        while (true) {
+        let activeModel = modelName;
+        retryLoop: while (true) {
             if (abortSignal?.aborted) {
                 const err = new Error('Operation aborted');
                 err.name = 'AbortError';
                 throw err;
             }
+            const endpoint = isStreaming ? 'streamGenerateContent?alt=sse&key=' : 'generateContent?key=';
+            const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(activeModel)}:${endpoint}${encodeURIComponent(apiKey)}`;
             const response = await fetch(url, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify(payload),
                 signal: abortSignal,
             });
-            debugLog(`BYOK Request to ${modelName} complete. Status: ${response.status} ${response.statusText}`);
-            if ((response.status === 429 ||
+            debugLog(`BYOK Request to ${activeModel} complete. Status: ${response.status} ${response.statusText}`);
+            if (response.status === 429 ||
                 response.status === 503 ||
                 response.status === 502 ||
                 response.status === 500 ||
-                response.status === 504) &&
-                attempt < MAX_RETRIES) {
-                if (abortSignal?.aborted) {
-                    const err = new Error('Operation aborted');
-                    err.name = 'AbortError';
-                    throw err;
+                response.status === 504) {
+                if (attempt < MAX_RETRIES) {
+                    if (abortSignal?.aborted) {
+                        const err = new Error('Operation aborted');
+                        err.name = 'AbortError';
+                        throw err;
+                    }
+                    const exponentialDelay = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * Math.pow(2, attempt));
+                    const delayTime = Math.round(exponentialDelay * (1.0 + Math.random() * 0.5));
+                    if (isDebugOn()) {
+                        process.stdout.write('\n');
+                        console.warn(`Server error or rate limit hit (${response.status}). Retrying in ${(delayTime / 1000).toFixed(1)}s... (Attempt ${attempt + 1}/${MAX_RETRIES})`);
+                    }
+                    await delay(delayTime, abortSignal);
+                    if (abortSignal?.aborted) {
+                        const err = new Error('Operation aborted');
+                        err.name = 'AbortError';
+                        throw err;
+                    }
+                    attempt++;
+                    continue;
                 }
-                const exponentialDelay = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * Math.pow(2, attempt));
-                const delayTime = Math.round(exponentialDelay * (1.0 + Math.random() * 0.5));
-                process.stdout.write('\n');
-                console.warn(`Server error or rate limit hit (${response.status}). Retrying in ${(delayTime / 1000).toFixed(1)}s... (Attempt ${attempt + 1}/${MAX_RETRIES})`);
-                await delay(delayTime, abortSignal);
-                if (abortSignal?.aborted) {
-                    const err = new Error('Operation aborted');
-                    err.name = 'AbortError';
-                    throw err;
+                else if (activeModel !== GEMINI_MODELS.FLASH_LITE) {
+                    debugLog(`BYOK rate limit retries exhausted (${MAX_RETRIES}/${MAX_RETRIES}) for ${activeModel}. Automatically falling back to ${GEMINI_MODELS.FLASH_LITE}...`);
+                    if (isDebugOn()) {
+                        process.stdout.write('\n');
+                        console.warn(`BYOK rate limit retries exhausted on ${activeModel}. Automatically switching to Flash-Lite (${GEMINI_MODELS.FLASH_LITE}) to complete request...`);
+                    }
+                    activeModel = GEMINI_MODELS.FLASH_LITE;
+                    attempt = 0;
+                    continue retryLoop;
                 }
-                attempt++;
-                continue;
             }
             if (!response.ok) {
                 let errorData = {};
@@ -427,7 +469,7 @@ export class ProxyClient {
                                         creditsUsed: 0,
                                         remainingBalance: 0,
                                     };
-                                    accumulateTurnUsage(data.usageMetadata, modelName);
+                                    accumulateTurnUsage(data.usageMetadata, activeModel);
                                 }
                             }
                             catch (parseError) {
@@ -436,6 +478,49 @@ export class ProxyClient {
                         }
                     }
                 }
+                catch (streamError) {
+                    if (abortSignal?.aborted || streamError.name === 'AbortError' || streamError.message?.includes('abort')) {
+                        const err = new Error('Operation aborted');
+                        err.name = 'AbortError';
+                        throw err;
+                    }
+                    if (streamError.message?.includes('429') ||
+                        streamError.message?.includes('502') ||
+                        streamError.message?.includes('503') ||
+                        streamError.message?.includes('500') ||
+                        streamError.message?.includes('504') ||
+                        streamError.message?.includes('Bad Gateway') ||
+                        streamError.message?.includes('RESOURCE_EXHAUSTED') ||
+                        streamError.message?.includes('Too Many Requests')) {
+                        if (attempt < MAX_RETRIES) {
+                            const exponentialDelay = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * Math.pow(2, attempt));
+                            const delayTime = Math.round(exponentialDelay * (1.0 + Math.random() * 0.5));
+                            if (isDebugOn()) {
+                                process.stdout.write('\n');
+                                console.warn(`Server error or rate limit hit during BYOK stream. Retrying in ${(delayTime / 1000).toFixed(1)}s... (Attempt ${attempt + 1}/${MAX_RETRIES})`);
+                            }
+                            await delay(delayTime, abortSignal);
+                            if (abortSignal?.aborted) {
+                                const err = new Error('Operation aborted');
+                                err.name = 'AbortError';
+                                throw err;
+                            }
+                            attempt++;
+                            continue retryLoop;
+                        }
+                        else if (activeModel !== GEMINI_MODELS.FLASH_LITE) {
+                            debugLog(`BYOK stream rate limit retries exhausted (${MAX_RETRIES}/${MAX_RETRIES}) for ${activeModel}. Automatically falling back to ${GEMINI_MODELS.FLASH_LITE}...`);
+                            if (isDebugOn()) {
+                                process.stdout.write('\n');
+                                console.warn(`BYOK stream rate limit exhausted on ${activeModel}. Automatically switching to Flash-Lite (${GEMINI_MODELS.FLASH_LITE}) to complete request...`);
+                            }
+                            activeModel = GEMINI_MODELS.FLASH_LITE;
+                            attempt = 0;
+                            continue retryLoop;
+                        }
+                    }
+                    throw streamError;
+                }
                 finally {
                     reader.releaseLock();
                 }
@@ -469,7 +554,7 @@ export class ProxyClient {
                         creditsUsed: 0,
                         remainingBalance: 0,
                     };
-                    accumulateTurnUsage(data.usageMetadata, modelName);
+                    accumulateTurnUsage(data.usageMetadata, activeModel);
                 }
             }
             return {

package/dist/services/workspaceRegistry.d.ts

@@ -24,15 +24,27 @@ export interface Profile {
  * Result of resolving an `@alias/relative/path` string against the workspace registry.
  */
 export interface ResolvedWorkspacePath {
-    /** The alias that was matched (e.g., "backend"). */
-    alias: string;
-    /** The absolute root directory of the matched registered workspace. */
+    /** The alias that was matched (e.g., "backend"), or null for primary workspace. */
+    alias: string | null;
+    /** The absolute root directory of the matched registered workspace or primary workspace. */
     workspaceRoot: string;
     /** The relative path within that workspace (e.g., "src/routes.ts"). */
     relativePath: string;
     /** The fully resolved absolute path to the target file or directory. */
     absolutePath: string;
+    /** Whether the path was resolved via primary sub-path auto-focusing. */
+    isAutoFocused?: boolean;
 }
+/**
+ * Returns the global configuration directory for Minovative Mind CLI.
+ * During automated tests, returns an isolated temporary directory to prevent test runs
+ * from modifying the developer's live workspace configurations.
+ */
+export declare function getGlobalConfigDir(): string;
+/**
+ * Returns the active path to the workspace registry JSON file.
+ */
+export declare function getRegistryFile(): string;
 /**
  * Service that manages a global registry of external workspace roots.
  *
@@ -54,11 +66,16 @@ declare class WorkspaceRegistry {
     private profiles;
     /** Whether the registry has been loaded from disk. */
     private initialized;
+    private primarySubPath;
     /**
      * Initializes the registry by loading persisted workspace entries from disk.
      * Safe to call multiple times — subsequent calls are no-ops.
      */
     init(): void;
+    /**
+     * Internal guard to guarantee the registry is loaded before any read or write operation.
+     */
+    private ensureInitialized;
     /**
      * Registers a new external workspace root with the given alias under a profile.
      *
@@ -124,15 +141,71 @@ declare class WorkspaceRegistry {
         root: string;
     }>;
     /**
-     * Resolves an `@alias/relative/path` string into its constituent parts.
+     * Sets the active primary sub-path for auto-focusing relative file queries.
+     *
+     * @param subPath - The relative directory path within the primary workspace (e.g., "src/services"), or null to clear.
+     */
+    setPrimarySubPath(subPath: string | null): void;
+    /**
+     * Returns the currently active primary sub-path, or null if none is set.
+     */
+    getPrimarySubPath(): string | null;
+    /**
+     * Returns whether a primary sub-path is currently active.
+     */
+    hasPrimarySubPath(): boolean;
+    /**
+     * Clears the active primary sub-path.
+     */
+    clearPrimarySubPath(): void;
+    /**
+     * Gets the focused root directory for the given primary workspace root.
+     * If a primary sub-path is active, returns the resolved sub-path directory;
+     * otherwise returns the primary root.
+     *
+     * @param primaryRoot - The base primary workspace root directory.
+     */
+    getFocusedRoot(primaryRoot: string): string;
+    /**
+     * Checks whether a target path is securely contained within a given boundary root.
+     *
+     * @param targetPath - The absolute or relative target path.
+     * @param boundaryRoot - The boundary root directory.
+     */
+    isPathWithinBoundary(targetPath: string, boundaryRoot: string): boolean;
+    /**
+     * Finds a registered workspace that contains the given file or directory path.
+     *
+     * @param targetPath - The file or directory path to check.
+     * @returns The matching `RegisteredWorkspace` or null if not found.
+     */
+    findWorkspaceForPath(targetPath: string): RegisteredWorkspace | null;
+    /**
+     * Checks whether a path resides inside the primary workspace or any registered workspace.
+     *
+     * @param targetPath - The file or directory path to inspect.
+     * @param primaryRoot - Optional primary workspace root.
+     */
+    isInsideRegisteredWorkspace(targetPath: string, primaryRoot?: string): boolean;
+    /**
+     * Resolves an `@alias/relative/path` string or primary workspace path into constituent parts.
      *
      * @param filePath - A file path that may or may not start with `@alias/`.
-     * @returns A `ResolvedWorkspacePath` if the path has a valid `@alias/` prefix
-     *   and the alias is registered, or `null` if the path is a standard
-     *   workspace-relative path (no `@` prefix or unrecognized alias).
+     * @param options - Optional resolution options including primaryRoot and autoFocusSubPath.
+     * @returns A `ResolvedWorkspacePath` if resolved, or `null` if the path cannot be resolved.
      * @throws Error if the path has an `@` prefix but the alias is not registered.
      */
-    resolve(filePath: string): ResolvedWorkspacePath | null;
+    resolve(filePath: string, options?: {
+        primaryRoot?: string;
+        autoFocusSubPath?: boolean;
+    }): ResolvedWorkspacePath | null;
+    /**
+     * Resolves a relative path against the primary root with automatic sub-path focusing.
+     *
+     * @param primaryRoot - The base primary workspace root directory.
+     * @param relativePath - The target relative path to resolve.
+     */
+    resolveWithAutoFocus(primaryRoot: string, relativePath: string): ResolvedWorkspacePath;
     /**
      * Checks if a given file path uses the `@alias/` prefix syntax.
      *