@ornexus/neocortex 3.8.0

package/packages/client/dist/commands/invoke.js

@@ -0,0 +1,345 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Invoke Command
+ *
+ * Primary entry point for server-side orchestration.
+ * Sends raw user args to POST /api/v1/invoke and returns
+ * complete orchestration instructions from the server.
+ *
+ * Story 45.2 - AC1-AC6
+ */
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { LicenseClient } from '../license/license-client.js';
+// ── Constants ─────────────────────────────────────────────────────────────
+const DEFAULT_SERVER_URL = 'https://api.neocortex.ornexus.com';
+const CONFIG_DIR = join(homedir(), '.neocortex');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+const CACHE_DIR = join(CONFIG_DIR, 'cache');
+const MENU_CACHE_FILE = join(CACHE_DIR, 'menu-cache.json');
+const MENU_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_TIMEOUT_MS = 30_000;
+// ── State Snapshot Collection ──────────────────────────────────────────────
+/**
+ * Read state.json and construct a sanitized snapshot for the server.
+ * Relative paths only - no absolute paths sent to server.
+ */
+export function collectStateSnapshot(projectRoot) {
+    const stateJsonPath = join(projectRoot, '.neocortex', 'state.json');
+    if (!existsSync(stateJsonPath)) {
+        // Return minimal snapshot if state.json doesn't exist
+        return {
+            config: {
+                project_name: 'unknown',
+                default_branch: 'main',
+                language: 'pt-BR',
+            },
+            stories: {},
+            epics: {},
+        };
+    }
+    let stateData;
+    try {
+        const raw = readFileSync(stateJsonPath, 'utf-8');
+        stateData = JSON.parse(raw);
+    }
+    catch {
+        return {
+            config: {
+                project_name: 'unknown',
+                default_branch: 'main',
+                language: 'pt-BR',
+            },
+            stories: {},
+            epics: {},
+        };
+    }
+    // Extract config - check both locations for compatibility
+    const config = (stateData.config ?? stateData.project ?? {});
+    // Extract stories - sanitize sensitive fields
+    const rawStories = (stateData.stories ?? {});
+    const stories = {};
+    for (const [id, story] of Object.entries(rawStories)) {
+        stories[id] = {
+            id: story.id ?? id,
+            title: story.title,
+            epic_id: story.epic_id,
+            status: story.status ?? 'backlog',
+            steps_completed: story.steps_completed ?? [],
+            last_step: story.last_step ?? null,
+            branch_name: story.branch_name ?? null,
+            pr_number: story.pr_number,
+            workflow_issue: story.workflow_issue,
+        };
+    }
+    // Extract epics
+    const rawEpics = (stateData.epics ?? {});
+    const epics = {};
+    for (const [id, epic] of Object.entries(rawEpics)) {
+        epics[id] = {
+            id: epic.id ?? id,
+            title: epic.title,
+            status: epic.status,
+            stories: epic.stories,
+            total_stories: epic.total_stories,
+            completed_stories: epic.completed_stories,
+        };
+    }
+    return {
+        config: {
+            project_name: (config.project_name ?? config.name ?? 'unknown'),
+            default_branch: (config.default_branch ?? 'main'),
+            language: (config.language ?? 'pt-BR'),
+            yolo_mode: config.yolo_mode,
+            user_name: config.user_name,
+            worktree_base: config.worktree_base,
+            max_parallel_stories: config.max_parallel_stories,
+        },
+        stories,
+        epics,
+    };
+}
+// ── Menu Cache ────────────────────────────────────────────────────────────
+function getMenuCache() {
+    try {
+        if (!existsSync(MENU_CACHE_FILE))
+            return null;
+        const raw = readFileSync(MENU_CACHE_FILE, 'utf-8');
+        const cache = JSON.parse(raw);
+        // Check TTL
+        if (Date.now() - cache.cachedAt > MENU_CACHE_TTL_MS) {
+            return null; // Expired
+        }
+        return cache;
+    }
+    catch {
+        return null;
+    }
+}
+function setMenuCache(instructions, metadata) {
+    try {
+        mkdirSync(CACHE_DIR, { recursive: true });
+        const cache = {
+            instructions,
+            metadata,
+            cachedAt: Date.now(),
+        };
+        writeFileSync(MENU_CACHE_FILE, JSON.stringify(cache), 'utf-8');
+    }
+    catch {
+        // Cache write failure is non-critical
+    }
+}
+// ── Config Loading ────────────────────────────────────────────────────────
+function loadConfig() {
+    try {
+        if (existsSync(CONFIG_FILE)) {
+            const raw = readFileSync(CONFIG_FILE, 'utf-8');
+            return JSON.parse(raw);
+        }
+    }
+    catch {
+        // Ignore
+    }
+    return null;
+}
+// ── Auth Token ────────────────────────────────────────────────────────────
+async function getAuthToken(serverUrl) {
+    try {
+        const client = new LicenseClient({ serverUrl, licenseKey: '' });
+        const token = await client.getToken();
+        return token;
+    }
+    catch {
+        return null;
+    }
+}
+// ── HTTP Request ──────────────────────────────────────────────────────────
+async function sendInvokeRequest(serverUrl, body, authToken) {
+    const url = `${serverUrl}/api/v1/invoke`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${authToken}`,
+                'X-Client-Version': '0.1.0',
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            let errorJson;
+            try {
+                errorJson = JSON.parse(errorText);
+            }
+            catch {
+                // Not JSON
+            }
+            return {
+                ok: false,
+                status: response.status,
+                error: errorJson
+                    ? `${errorJson.error_code ?? 'ERROR'}: ${errorJson.message ?? errorText}`
+                    : `HTTP ${response.status}: ${errorText}`,
+            };
+        }
+        const data = (await response.json());
+        return { ok: true, status: response.status, data };
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            status: 0,
+            error: message.includes('abort')
+                ? `Request timeout after ${DEFAULT_TIMEOUT_MS / 1000}s`
+                : `Network error: ${message}`,
+        };
+    }
+}
+// ── Main Invoke Function ──────────────────────────────────────────────────
+/**
+ * Execute the invoke command.
+ *
+ * Flow:
+ * 1. Load config to get server URL
+ * 2. Collect state snapshot from project root
+ * 3. Check menu cache for empty invocations
+ * 4. Send POST /api/v1/invoke
+ * 5. Format and return result
+ */
+export async function invoke(options) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const format = options.format ?? 'plain';
+    const platformTarget = options.platformTarget ?? 'claude-code';
+    // 1. Determine server URL
+    const config = loadConfig();
+    const serverUrl = (options.serverUrl ?? config?.serverUrl ?? DEFAULT_SERVER_URL).replace(/\/+$/, '');
+    // 2. Collect state snapshot
+    const stateSnapshot = collectStateSnapshot(projectRoot);
+    // 3. Check menu cache for empty invocations (AC6)
+    const trimmedArgs = options.args.trim();
+    if (!trimmedArgs) {
+        const cachedMenu = getMenuCache();
+        if (cachedMenu) {
+            return {
+                success: true,
+                instructions: cachedMenu.instructions,
+                metadata: cachedMenu.metadata,
+                exitCode: 0,
+            };
+        }
+    }
+    // 4. Get auth token
+    const authToken = await getAuthToken(serverUrl);
+    if (!authToken) {
+        return {
+            success: false,
+            error: 'Not authenticated. Run: neocortex activate NX-PRO-xxx',
+            exitCode: 2, // Not configured
+        };
+    }
+    // 5. Send request
+    const result = await sendInvokeRequest(serverUrl, {
+        args: trimmedArgs,
+        projectRoot: projectRoot.replace(homedir(), '~'), // Sanitize absolute path
+        stateSnapshot,
+        platformTarget,
+    }, authToken);
+    if (!result.ok || !result.data) {
+        // AC5: Error exit code
+        const exitCode = result.status === 401 ? 2 :
+            result.status === 429 ? 1 :
+                result.status >= 500 ? 1 : 1;
+        return {
+            success: false,
+            error: result.error ?? 'Unknown error from server',
+            exitCode,
+        };
+    }
+    // 6. Cache menu responses (AC6)
+    if (!trimmedArgs && result.data.metadata?.mode === 'menu') {
+        setMenuCache(result.data.instructions, result.data.metadata);
+    }
+    return {
+        success: true,
+        instructions: result.data.instructions,
+        metadata: result.data.metadata,
+        exitCode: 0,
+    };
+}
+// ── CLI Entry Point ───────────────────────────────────────────────────────
+/**
+ * CLI handler for the invoke command.
+ * Parses CLI args and delegates to invoke().
+ *
+ * Usage:
+ *   neocortex-client invoke --args "*yolo @story.md" --project-root /path
+ *   neocortex-client invoke --args "*status" --format json
+ */
+export async function invokeCliHandler(argv) {
+    let args = '';
+    let projectRoot = process.cwd();
+    let format = 'plain';
+    let serverUrl;
+    // Parse CLI arguments
+    for (let i = 0; i < argv.length; i++) {
+        switch (argv[i]) {
+            case '--args':
+                args = argv[++i] ?? '';
+                break;
+            case '--project-root':
+                projectRoot = argv[++i] ?? process.cwd();
+                break;
+            case '--format':
+                format = (argv[++i] ?? 'plain');
+                break;
+            case '--server-url':
+                serverUrl = argv[++i];
+                break;
+        }
+    }
+    const result = await invoke({ args, projectRoot, format, serverUrl });
+    if (!result.success) {
+        // AC5: Error to stderr as JSON
+        process.stderr.write(JSON.stringify({
+            error_code: result.exitCode === 2 ? 'NOT_CONFIGURED' : 'INVOKE_ERROR',
+            message: result.error,
+        }) + '\n');
+        return result.exitCode;
+    }
+    if (format === 'json') {
+        // AC3: Full JSON to stdout
+        process.stdout.write(JSON.stringify({
+            instructions: result.instructions,
+            metadata: result.metadata,
+        }) + '\n');
+    }
+    else {
+        // AC4: Instructions to stdout, metadata to stderr
+        process.stdout.write((result.instructions ?? '') + '\n');
+        if (result.metadata) {
+            process.stderr.write(JSON.stringify(result.metadata) + '\n');
+        }
+    }
+    return 0;
+}
+//# sourceMappingURL=invoke.js.map

package/packages/client/dist/commands/invoke.js.map

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

package/packages/client/dist/config/resolver-selection.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+import type { AssetResolver } from '../resolvers/asset-resolver.js';
+import type { CreateResolverOptions } from '../types/index.js';
+/** Result of resolver selection including the reason for the choice */
+export interface ResolverSelectionResult {
+    readonly resolver: AssetResolver;
+    readonly reason: string;
+    readonly mode: 'local' | 'remote';
+}
+/**
+ * Create the appropriate AssetResolver based on configuration.
+ *
+ * Selection follows a strict priority chain:
+ * 1. forceLocal option -> LocalResolver
+ * 2. NEOCORTEX_MODE=local -> LocalResolver
+ * 3. NEOCORTEX_MODE=remote -> RemoteResolver
+ * 4. core/ exists locally -> LocalResolver
+ * 5. License key + no core/ -> RemoteResolver
+ * 6. Default -> LocalResolver
+ *
+ * @param options - Optional configuration overrides
+ * @returns Configured AssetResolver ready for use
+ */
+export declare function createResolver(options?: CreateResolverOptions): Promise<AssetResolver>;
+/**
+ * Select resolver with full result including reason.
+ * Useful for logging/debugging why a specific resolver was chosen.
+ */
+export declare function selectResolver(options?: CreateResolverOptions): Promise<ResolverSelectionResult>;
+//# sourceMappingURL=resolver-selection.d.ts.map

package/packages/client/dist/config/resolver-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver-selection.d.ts","sourceRoot":"","sources":["../../src/config/resolver-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAGpE,OAAO,KAAK,EAAiB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAI9E,uEAAuE;AACvE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;CACnC;AA0JD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,aAAa,CAAC,CAGxB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAgGlC"}

package/packages/client/dist/config/resolver-selection.js

@@ -0,0 +1,278 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Resolver Selection Factory
+ *
+ * Factory function that selects the appropriate AssetResolver
+ * based on CLI flags, environment variables, and auto-detection.
+ *
+ * Decision chain (priority order):
+ * 1. forceLocal option (--local flag) -> LocalResolver
+ * 2. NEOCORTEX_MODE=local env -> LocalResolver
+ * 3. NEOCORTEX_MODE=remote env -> RemoteResolver
+ * 4. core/ directory exists locally -> LocalResolver (dev mode)
+ * 4.5. Feature flag cutover (hash(machine) % 100 < remotePercentage) -> RemoteResolver
+ * 5. Valid license key present + no core/ -> RemoteResolver
+ * 6. Default -> LocalResolver (safe fallback)
+ */
+import { access, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { LocalResolver } from '../resolvers/local-resolver.js';
+import { RemoteResolver } from '../resolvers/remote-resolver.js';
+// ── Feature Flag (Story 43.7) ───────────────────────────────────────────
+const CONFIG_CACHE_FILE = join(homedir(), '.neocortex', 'feature-flags.json');
+const CONFIG_CACHE_TTL_MS = 3600_000; // 1 hour
+/**
+ * Check if this machine should use remote mode based on server feature flags.
+ * Uses hash(machine_fingerprint) % 100 < remotePercentage to determine bucket.
+ * Caches the server config for 1 hour.
+ *
+ * Returns 'remote' | 'local' | 'skip' (skip = no flag applies)
+ */
+async function checkFeatureFlag(options) {
+    try {
+        // Check env override
+        const envPercentage = process.env['NEOCORTEX_REMOTE_PERCENTAGE'];
+        if (envPercentage !== undefined) {
+            const pct = parseInt(envPercentage, 10);
+            if (isNaN(pct) || pct <= 0)
+                return 'skip';
+            return isInRemoteBucket(pct) ? 'remote' : 'local';
+        }
+        // Try cached config
+        const cached = await loadFeatureFlagCache();
+        if (cached) {
+            if (cached.forceLocal)
+                return 'local';
+            if (cached.forceRemote)
+                return 'remote';
+            if (cached.remotePercentage <= 0)
+                return 'skip';
+            return isInRemoteBucket(cached.remotePercentage) ? 'remote' : 'local';
+        }
+        // Fetch from server (non-blocking, fail gracefully)
+        const serverUrl = getServerUrl(options);
+        const config = await fetchFeatureFlags(serverUrl);
+        if (config) {
+            await saveFeatureFlagCache(config);
+            if (config.forceLocal)
+                return 'local';
+            if (config.forceRemote)
+                return 'remote';
+            if (config.remotePercentage <= 0)
+                return 'skip';
+            return isInRemoteBucket(config.remotePercentage) ? 'remote' : 'local';
+        }
+        return 'skip'; // No flag info available
+    }
+    catch {
+        return 'skip'; // Never block on feature flag errors
+    }
+}
+/**
+ * Deterministic bucket assignment using machine fingerprint hash.
+ * hash(machine_id) % 100 < percentage = in remote bucket
+ */
+function isInRemoteBucket(percentage) {
+    const machineId = process.env['NEOCORTEX_MACHINE_ID'] ?? 'default';
+    const hash = createHash('sha256').update(machineId).digest();
+    const bucket = hash.readUInt16BE(0) % 100;
+    return bucket < percentage;
+}
+async function loadFeatureFlagCache() {
+    try {
+        const raw = await readFile(CONFIG_CACHE_FILE, 'utf-8');
+        const cached = JSON.parse(raw);
+        if (Date.now() - cached.fetchedAt < CONFIG_CACHE_TTL_MS) {
+            return cached;
+        }
+        return null; // Expired
+    }
+    catch {
+        return null;
+    }
+}
+async function saveFeatureFlagCache(config) {
+    try {
+        await mkdir(join(homedir(), '.neocortex'), { recursive: true });
+        await writeFile(CONFIG_CACHE_FILE, JSON.stringify(config), 'utf-8');
+    }
+    catch {
+        // Non-critical - ignore
+    }
+}
+async function fetchFeatureFlags(serverUrl) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const response = await fetch(`${serverUrl}/api/v1/config`, {
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        return {
+            remotePercentage: data.remotePercentage ?? 0,
+            forceRemote: data.forceRemote ?? false,
+            forceLocal: data.forceLocal ?? false,
+            fetchedAt: Date.now(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ── Detection Helpers ───────────────────────────────────────────────────
+/**
+ * Check if the core/ directory exists at the given project root.
+ * This indicates development mode.
+ */
+async function detectLocalMode(projectRoot) {
+    try {
+        await access(join(projectRoot, 'core'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get license key from environment or options.
+ */
+function getLicenseKey(options) {
+    return options?.licenseKey || process.env['NEOCORTEX_LICENSE_KEY'] || undefined;
+}
+/**
+ * Get server URL from environment or options.
+ */
+function getServerUrl(options) {
+    return (options?.serverUrl ||
+        process.env['NEOCORTEX_SERVER_URL'] ||
+        'https://api.neocortex.dev');
+}
+// ── Factory Function ────────────────────────────────────────────────────
+/**
+ * Create the appropriate AssetResolver based on configuration.
+ *
+ * Selection follows a strict priority chain:
+ * 1. forceLocal option -> LocalResolver
+ * 2. NEOCORTEX_MODE=local -> LocalResolver
+ * 3. NEOCORTEX_MODE=remote -> RemoteResolver
+ * 4. core/ exists locally -> LocalResolver
+ * 5. License key + no core/ -> RemoteResolver
+ * 6. Default -> LocalResolver
+ *
+ * @param options - Optional configuration overrides
+ * @returns Configured AssetResolver ready for use
+ */
+export async function createResolver(options) {
+    const result = await selectResolver(options);
+    return result.resolver;
+}
+/**
+ * Select resolver with full result including reason.
+ * Useful for logging/debugging why a specific resolver was chosen.
+ */
+export async function selectResolver(options) {
+    const projectRoot = resolve(options?.projectRoot || process.cwd());
+    const neocortexMode = process.env['NEOCORTEX_MODE']?.toLowerCase();
+    // 1. forceLocal option (--local CLI flag)
+    if (options?.forceLocal) {
+        return {
+            resolver: new LocalResolver({ projectRoot }),
+            reason: 'Forced local mode via --local flag',
+            mode: 'local',
+        };
+    }
+    // 2. NEOCORTEX_MODE=local
+    if (neocortexMode === 'local') {
+        return {
+            resolver: new LocalResolver({ projectRoot }),
+            reason: 'NEOCORTEX_MODE=local environment variable',
+            mode: 'local',
+        };
+    }
+    // 3. NEOCORTEX_MODE=remote
+    if (neocortexMode === 'remote') {
+        const licenseKey = getLicenseKey(options);
+        if (!licenseKey) {
+            // Fall back to local if no license key for remote mode
+            return {
+                resolver: new LocalResolver({ projectRoot }),
+                reason: 'NEOCORTEX_MODE=remote but no license key found, falling back to local',
+                mode: 'local',
+            };
+        }
+        return {
+            resolver: new RemoteResolver({
+                serverUrl: getServerUrl(options),
+                licenseKey,
+                cacheProvider: options?.cacheProvider,
+                licenseClient: options?.licenseClient,
+            }),
+            reason: 'NEOCORTEX_MODE=remote environment variable',
+            mode: 'remote',
+        };
+    }
+    // 4. Auto-detect: core/ directory exists -> dev mode
+    const hasLocalCore = await detectLocalMode(projectRoot);
+    if (hasLocalCore) {
+        return {
+            resolver: new LocalResolver({ projectRoot }),
+            reason: 'Auto-detected development mode (core/ directory exists)',
+            mode: 'local',
+        };
+    }
+    // 4.5. Feature flag cutover check (Story 43.7)
+    // If server config says remotePercentage > 0, check if this machine is in the bucket
+    const featureFlagResult = await checkFeatureFlag(options);
+    if (featureFlagResult === 'remote') {
+        const licenseKey = getLicenseKey(options);
+        if (licenseKey) {
+            return {
+                resolver: new RemoteResolver({
+                    serverUrl: getServerUrl(options),
+                    licenseKey,
+                    cacheProvider: options?.cacheProvider,
+                    licenseClient: options?.licenseClient,
+                }),
+                reason: 'Feature flag cutover: machine in remote bucket',
+                mode: 'remote',
+            };
+        }
+    }
+    // 5. License key present + no core/ -> production mode
+    const licenseKey = getLicenseKey(options);
+    if (licenseKey) {
+        return {
+            resolver: new RemoteResolver({
+                serverUrl: getServerUrl(options),
+                licenseKey,
+                cacheProvider: options?.cacheProvider,
+                licenseClient: options?.licenseClient,
+            }),
+            reason: 'Auto-detected production mode (license key present, no core/ directory)',
+            mode: 'remote',
+        };
+    }
+    // 6. Default -> LocalResolver (safe fallback)
+    return {
+        resolver: new LocalResolver({ projectRoot }),
+        reason: 'Default fallback to local mode',
+        mode: 'local',
+    };
+}
+//# sourceMappingURL=resolver-selection.js.map