@gitsense/gsc-utils 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitsense/gsc-utils",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Utilities for GitSense Chat (GSC)",
   "main": "dist/gsc-utils.cjs.js",
   "module": "dist/gsc-utils.esm.js",

package/src/AnalyzerUtils/discovery.js

@@ -0,0 +1,139 @@
+/*
+ * Component: AnalyzerUtils Discovery
+ * Block-UUID: 0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5f
+ * Parent-UUID: N/A
+ * Version: 1.0.0
+ * Description: Provides utility functions for discovering available analyzers.
+ * Language: JavaScript
+ * Created-at: 2025-08-28T23:48:00.000Z
+ * Authors: Gemini 2.5 Flash (v1.0.0)
+ */
+
+
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * Reads and parses the config.json file in a directory.
+ * @param {string} dirPath - The path to the directory.
+ * @returns {Promise<object|null>} A promise that resolves to the parsed config object
+ *                                 or null if the file doesn't exist or is invalid.
+ */
+async function readConfig(dirPath) {
+    const configPath = path.join(dirPath, 'config.json');
+    try {
+        const fileContent = await fs.readFile(configPath, 'utf8');
+        return JSON.parse(fileContent);
+    } catch (error) {
+        if (error.code !== 'ENOENT') {
+            // Log a warning if config.json exists but is malformed
+            console.warn(`Warning: Failed to parse config.json in ${dirPath}: ${error.message}`);
+        }
+        return null; // Return null if file not found or parsing failed
+    }
+}
+
+/**
+ * Checks if a directory name is valid based on the rules in messages/analyze/README.md.
+ * Allowed: a-z, A-Z, 0-9, dash (-), underscore (_). Cannot start with underscore or contain dots.
+ * @param {string} name - The directory name to check.
+ * @returns {boolean} True if the name is valid, false otherwise.
+ */
+function isValidDirName(name) {
+    // Exclude names starting with underscore or containing dots
+    if (name.startsWith('_') || name.includes('.')) {
+        return false;
+    }
+    // Check for allowed characters
+    return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+
+/**
+ * Discovers and lists all available analyzers by traversing the directory structure.
+ * An analyzer is considered valid if a '1.md' file exists in the instructions directory.
+ *
+ * @param {string} analyzeMessagesBasePath - The absolute or relative path to the base directory containing the analyzer message files (e.g., 'messages/analyze').
+ * @returns {Promise<Array<{id: string, label: string}>>} A promise that resolves to an array of analyzer objects.
+ */
+async function getAnalyzers(analyzeMessagesBasePath) {
+    const analyzers = [];
+
+    try {
+        const analyzerEntries = await fs.readdir(analyzeMessagesBasePath, { withFileTypes: true });
+
+        for (const analyzerEntry of analyzerEntries) {
+            if (analyzerEntry.isDirectory() && isValidDirName(analyzerEntry.name)) {
+                const analyzerName = analyzerEntry.name;
+                const analyzerPath = path.join(analyzeMessagesBasePath, analyzerName);
+                const analyzerConfig = await readConfig(analyzerPath);
+                const analyzerLabel = analyzerConfig?.label || analyzerName;
+
+                const contentEntries = await fs.readdir(analyzerPath, { withFileTypes: true });
+
+                for (const contentEntry of contentEntries) {
+                    if (contentEntry.isDirectory() && isValidDirName(contentEntry.name)) {
+                        const contentType = contentEntry.name;
+                        const contentPath = path.join(analyzerPath, contentType);
+                        const contentConfig = await readConfig(contentPath);
+                        const contentLabel = contentConfig?.label || contentType;
+
+                        const instructionsEntries = await fs.readdir(contentPath, { withFileTypes: true });
+
+                        for (const instructionsEntry of instructionsEntries) {
+                            if (instructionsEntry.isDirectory() && isValidDirName(instructionsEntry.name)) {
+                                const instructionsType = instructionsEntry.name;
+                                const instructionsPath = path.join(contentPath, instructionsType);
+                                const instructionsConfig = await readConfig(instructionsPath);
+                                const instructionsLabel = instructionsConfig?.label || instructionsType;
+
+                                // Check for the existence of 1.md to confirm a valid analyzer configuration
+                                const instructionsFilePath = path.join(instructionsPath, '1.md');
+                                try {
+                                    await fs.access(instructionsFilePath); // Check if file exists and is accessible
+
+                                    // If analyzerName starts with 'tutorial-', check its last modified time.
+                                    if (analyzerName.startsWith('tutorial-')) {
+                                        const stats = await fs.stat(instructionsFilePath);
+                                        const lastModified = stats.mtime.getTime(); // Get timestamp in milliseconds
+                                        const sixtyMinutesAgo = Date.now() - (60 * 60 * 1000); // Current time - 60 minutes in ms
+
+                                        if (lastModified < sixtyMinutesAgo) {
+                                            // This tutorial analyzer has expired, skip it.
+                                            continue;
+                                        }
+                                    }
+                                    // Construct the analyzer ID and label
+                                    const analyzerId = `${analyzerName}::${contentType}::${instructionsType}`;
+                                    const analyzerFullLabel = `${analyzerLabel} (${contentLabel} - ${instructionsLabel})`;
+
+                                    analyzers.push({
+                                        id: analyzerId,
+                                        label: analyzerFullLabel,
+                                        protected: analyzerConfig?.protected || false
+                                    });
+                                } catch (error) {
+                                    // If 1.md doesn't exist, this is not a complete analyzer configuration, skip.
+                                    if (error.code !== 'ENOENT') {
+                                        console.warn(`Warning: Error accessing 1.md for ${analyzerId}: ${error.message}`);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    } catch (error) {
+        console.error(`Error traversing analyze messages directory ${analyzeMessagesBasePath}: ${error.message}`);
+        // Depending on requirements, you might want to throw the error or return an empty array
+        throw error; // Re-throw to indicate failure
+    }
+
+    return analyzers;
+}
+
+module.exports = {
+    getAnalyzers,
+    readConfig,
+    isValidDirName,
+};

package/src/AnalyzerUtils/index.js

@@ -2,20 +2,28 @@
  * Component: AnalyzerUtils Index
  * Block-UUID: b403b6a1-230b-4247-8cd6-2a3d068f4bbf
  * Parent-UUID: N/A
- * Version: 1.0.0
+ * Version: 1.1.0
  * Description: Aggregates and exports all utility functions from the AnalyzerUtils module.
  * Language: JavaScript
  * Created-at: 2025-08-28T15:56:40.319Z
- * Authors: Gemini 2.5 Flash (v1.0.0)
+ * Authors: Gemini 2.5 Flash (v1.0.0), Gemini 2.5 Flash (v1.1.0)
  */
 
 
 const { buildChatIdToPathMap } = require('./contextMapper');
 const { processLLMAnalysisResponse } = require('./responseProcessor');
 const { validateLLMAnalysisData } = require('./dataValidator');
+const { getAnalyzers } = require('./discovery');
+const { getAnalyzerSchema } = require('./schemaLoader');
+const { deleteAnalyzer } = require('./management');
+const { getAnalyzerInstructionsContent } = require('./instructionLoader');
 
 module.exports = {
     buildChatIdToPathMap,
     processLLMAnalysisResponse,
-    validateLLMAnalysisData
+    validateLLMAnalysisData,
+    getAnalyzers,
+    getAnalyzerSchema,
+    deleteAnalyzer,
+    getAnalyzerInstructionsContent,
 };

package/src/AnalyzerUtils/instructionLoader.js

@@ -0,0 +1,58 @@
+/*
+ * Component: AnalyzerUtils Instruction Loader
+ * Block-UUID: 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5e
+ * Parent-UUID: N/A
+ * Version: 1.0.0
+ * Description: Provides utility functions for loading raw analyzer instruction content.
+ * Language: JavaScript
+ * Created-at: 2025-08-28T23:48:00.000Z
+ * Authors: Gemini 2.5 Flash (v1.0.0)
+ */
+
+
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * Retrieves the raw Markdown content of the analyzer's '1.md' instruction file.
+ *
+ * @param {string} analyzeMessagesBasePath - The absolute path to the base directory containing the analyzer message files (e.g., 'messages/analyze').
+ * @param {string} analyzerId - The unique ID of the analyzer (format: 'analyzer_name::content_type::instructions_type').
+ * @returns {Promise<string|null>} A promise that resolves with the full Markdown content of the '1.md' file, or null if not found/invalid.
+ */
+async function getAnalyzerInstructionsContent(analyzeMessagesBasePath, analyzerId) {
+    if (typeof analyzeMessagesBasePath !== 'string' || analyzeMessagesBasePath.trim() === '') {
+        console.error('Error: analyzeMessagesBasePath is required.');
+        return null;
+    }
+    if (typeof analyzerId !== 'string' || analyzerId.trim() === '') {
+        console.error('Error: analyzerId is required.');
+        return null;
+    }
+
+    const parts = analyzerId.split('::');
+    if (parts.length !== 3) {
+        console.error(`Error: Invalid analyzerId format. Expected 'analyzer_name::content_type::instructions_type', but got '${analyzerId}'.`);
+        return null;
+    }
+    const [analyzerName, contentType, instructionsType] = parts;
+
+    const instructionsFilePath = path.join(analyzeMessagesBasePath, analyzerName, contentType, instructionsType, '1.md');
+
+    try {
+        const fileContent = await fs.readFile(instructionsFilePath, 'utf8');
+        return fileContent;
+    } catch (error) {
+        if (error.code === 'ENOENT') {
+            console.warn(`Analyzer instructions file not found: ${instructionsFilePath}`);
+            return null;
+        } else {
+            console.error(`Error reading analyzer instructions file ${instructionsFilePath}: ${error.message}`);
+            throw error;
+        }
+    }
+}
+
+module.exports = {
+    getAnalyzerInstructionsContent
+};

package/src/AnalyzerUtils/management.js

@@ -0,0 +1,131 @@
+/*
+ * Component: AnalyzerUtils Management
+ * Block-UUID: 0d1e2f3a-4b5c-6d7e-8f9a-0b1c2d3e4f5a
+ * Parent-UUID: N/A
+ * Version: 1.0.0
+ * Description: Provides utility functions for managing (deleting) analyzer configurations.
+ * Language: JavaScript
+ * Created-at: 2025-08-28T23:48:00.000Z
+ * Authors: Gemini 2.5 Flash (v1.0.0)
+ */
+
+
+const fs = require('fs').promises;
+const path = require('path');
+const { readConfig } = require('./discovery'); // Import helper from discovery
+
+/**
+ * Checks if a directory is empty or only contains a config.json.
+ * @param {string} dirPath - The path to the directory.
+ * @returns {Promise<boolean>} True if the directory is empty or only contains config.json, false otherwise.
+ */
+async function isDirectoryEmpty(dirPath) {
+    try {
+        const files = await fs.readdir(dirPath);
+        return files.length === 0 || (files.length === 1 && files[0] === 'config.json');
+    } catch (error) {
+        if (error.code === 'ENOENT') {
+            return true; // Directory doesn't exist, so it's "empty" for our purpose
+        }
+        throw error; // Re-throw other errors
+    }
+}
+
+/**
+ * Deletes a specific analyzer configuration and intelligently cleans up empty directories.
+ *
+ * @param {string} analyzeMessagesBasePath - The absolute or relative path to the base directory containing the analyzer message files (e.g., 'messages/analyze').
+ * @param {string} analyzerId - The unique ID of the analyzer to delete (format: 'analyzer_name::content_type::instructions_type').
+ * @returns {Promise<{success: boolean, message: string}>} A promise that resolves with a result object indicating success or failure.
+ */
+async function deleteAnalyzer(analyzeMessagesBasePath, analyzerId) {
+    if (typeof analyzeMessagesBasePath !== 'string' || analyzeMessagesBasePath.trim() === '') {
+        return { success: false, message: 'analyzeMessagesBasePath is required.' };
+    }
+    if (typeof analyzerId !== 'string' || analyzerId.trim() === '') {
+        return { success: false, message: 'analyzerId is required.' };
+    }
+
+    const parts = analyzerId.split('::');
+    if (parts.length !== 3) {
+        return { success: false, message: `Invalid analyzerId format. Expected 'analyzer_name::content_type::instructions_type', but got '${analyzerId}'.` };
+    }
+    const [analyzerName, contentType, instructionsType] = parts;
+
+    const analyzerDir = path.join(analyzeMessagesBasePath, analyzerName);
+    const contentDir = path.join(analyzerDir, contentType);
+    const instructionsDir = path.join(contentDir, instructionsType);
+    const instructionsFilePath = path.join(instructionsDir, '1.md');
+
+    try {
+        // 1. Check for protection at all levels
+        const analyzerConfig = await readConfig(analyzerDir);
+        if (analyzerConfig?.protected) {
+            return { success: false, message: `Analyzer '${analyzerName}' is protected and cannot be deleted.` };
+        }
+
+        const contentConfig = await readConfig(contentDir);
+        if (contentConfig?.protected) {
+            return { success: false, message: `Content type '${contentType}' for analyzer '${analyzerName}' is protected and cannot be deleted.` };
+        }
+
+        const instructionsConfig = await readConfig(instructionsDir);
+        if (instructionsConfig?.protected) {
+            return { success: false, message: `Instructions type '${instructionsType}' for content type '${contentType}' is protected and cannot be deleted.` };
+        }
+
+        // 2. Delete the 1.md file
+        try {
+            await fs.unlink(instructionsFilePath);
+        } catch (error) {
+            if (error.code === 'ENOENT') {
+                return { success: false, message: `Analyzer instructions file not found: ${instructionsFilePath}. It may have already been deleted.` };
+            }
+            throw error; // Re-throw other errors
+        }
+
+        // 3. Intelligently delete empty directories, cascading upwards
+        let deletedDirs = [];
+
+        // Check and delete instructions directory
+        if (await isDirectoryEmpty(instructionsDir)) {
+            try {
+                await fs.rmdir(instructionsDir);
+                deletedDirs.push(instructionsDir);
+            } catch (error) {
+                console.warn(`Warning: Could not remove empty instructions directory ${instructionsDir}: ${error.message}`);
+            }
+        }
+
+        // Check and delete content directory
+        if (await isDirectoryEmpty(contentDir)) {
+            try {
+                await fs.rmdir(contentDir);
+                deletedDirs.push(contentDir);
+            } catch (error) {
+                console.warn(`Warning: Could not remove empty content directory ${contentDir}: ${error.message}`);
+            }
+        }
+
+        // Check and delete analyzer directory
+        if (await isDirectoryEmpty(analyzerDir)) {
+            try {
+                await fs.rmdir(analyzerDir);
+                deletedDirs.push(analyzerDir);
+            } catch (error) {
+                console.warn(`Warning: Could not remove empty analyzer directory ${analyzerDir}: ${error.message}`);
+            }
+        }
+
+        return { success: true, message: `Analyzer '${analyzerId}' deleted successfully. Cleaned up directories: ${deletedDirs.join(', ') || 'None'}.` };
+
+    } catch (error) {
+        console.error(`Error deleting analyzer '${analyzerId}': ${error.message}`);
+        return { success: false, message: `Failed to delete analyzer: ${error.message}` };
+    }
+}
+
+module.exports = {
+    deleteAnalyzer,
+    isDirectoryEmpty,
+};

package/src/AnalyzerUtils/schemaLoader.js

@@ -0,0 +1,163 @@
+/*
+ * Component: AnalyzerUtils Schema Loader
+ * Block-UUID: 0c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f
+ * Parent-UUID: N/A
+ * Version: 1.0.0
+ * Description: Provides utility functions for retrieving and deducing JSON schemas for analyzers.
+ * Language: JavaScript
+ * Created-at: 2025-08-28T23:48:00.000Z
+ * Authors: Gemini 2.5 Flash (v1.0.0)
+ */
+
+
+const fs = require('fs').promises;
+const path = require('path');
+const CodeBlockUtils = require('../CodeBlockUtils');
+
+/**
+ * Deduces the JSON schema type and format/items from a string value pattern.
+ * Handles patterns like "[string: ...]", "[number: ...]", "[datetime: ...]", "[<string>: ...]",
+ * and boolean instructions. Defaults to 'string' for unknown patterns.
+ *
+ * @param {any} value - The value from the raw JSON (expected to be a string pattern).
+ * @param {string} fieldName - The name of the field (for logging warnings).
+ * @returns {{type: string, format?: string, items?: object}} An object describing the schema type and format/items.
+ */
+function deduceSchemaType(value, fieldName) {
+    const defaultSchema = { type: 'string' }; // Default fallback
+
+    if (typeof value !== 'string') {
+        const jsType = typeof value;
+        if (jsType === 'object' && value !== null) {
+            console.warn(`Warning: Unexpected non-string, non-null object/array value for field "${fieldName}". Defaulting to type 'string'. Value:`, value);
+            return defaultSchema;
+        }
+        return { type: jsType };
+    }
+
+    const trimmedValue = value.trim();
+
+    if (/^\[string:.*\]$/.test(trimmedValue) || (/^\[[^:]+\]$/.test(trimmedValue) && !/^\[(number|datetime|date|<string>):.*\]$/.test(trimmedValue))) {
+        return { type: 'string' };
+    }
+
+    if (/^\[number:.*\]$/.test(trimmedValue)) {
+        return { type: 'number' };
+    }
+
+    if (/^\[boolean:.*\]$/.test(trimmedValue)) {
+        return { type: 'boolean' };
+    }
+
+    if (/^\[date-*time:.*\]$/.test(trimmedValue)) {
+        return { type: 'string', format: 'date-time' };
+    }
+
+    if (/^\[date:.*\]$/.test(trimmedValue)) {
+        return { type: 'string', format: 'date' };
+    }
+
+    if (/^\[<string>:.*\]$/.test(trimmedValue) || trimmedValue.toLowerCase().includes('array of strings')) {
+        return { type: 'array', items: { type: 'string' } };
+    }
+
+    if (trimmedValue.toLowerCase().includes("output 'true' or 'false'") || trimmedValue.toLowerCase().includes("determine if") && (trimmedValue.toLowerCase().includes("true") || trimmedValue.toLowerCase().includes("false"))) {
+        return { type: 'boolean' };
+    }
+
+    console.warn(`Warning: Unknown metadata value pattern for field "${fieldName}". Defaulting to type 'string'. Value: "${value}"`);
+    return defaultSchema;
+}
+
+
+/**
+ * Retrieves the JSON schema for a specific analyzer.
+ * Reads the corresponding '1.md' file, extracts the JSON block,
+ * and deduces schema types from the string values.
+ *
+ * @param {string} analyzeMessagesBasePath - The absolute or relative path to the base directory containing the analyzer message files (e.g., 'messages/analyze').
+ * @param {string} analyzerId - The unique ID of the analyzer (format: 'analyzer_name::content_type::instructions_type').
+ * @returns {Promise<object|null>} A promise that resolves with the JSON schema object or null if the analyzer ID is invalid or the schema cannot be retrieved/parsed.
+ * @throws {Error} If the 1.md file is found but does not contain exactly one JSON code block.
+ */
+async function getAnalyzerSchema(analyzeMessagesBasePath, analyzerId) {
+    if (typeof analyzeMessagesBasePath !== 'string' || analyzeMessagesBasePath.trim() === '') {
+        console.error('Error: analyzeMessagesBasePath is required.');
+        return null;
+    }
+    if (typeof analyzerId !== 'string' || analyzerId.trim() === '') {
+        console.error('Error: analyzerId is required.');
+        return null;
+    }
+
+    const parts = analyzerId.split('::');
+    if (parts.length !== 3) {
+        console.error(`Error: Invalid analyzerId format. Expected 'analyzer_name::content_type::instructions_type', but got '${analyzerId}'.`);
+        return null;
+    }
+    const [analyzerName, contentType, instructionsType] = parts;
+
+    const instructionsFilePath = path.join(analyzeMessagesBasePath, analyzerName, contentType, instructionsType, '1.md');
+
+    try {
+        const fileContent = await fs.readFile(instructionsFilePath, 'utf8');
+        const { blocks } = CodeBlockUtils.extractCodeBlocks(fileContent, { silent: true });
+        const jsonBlocks = blocks.filter(block => block.type === 'code' && block.language === 'json');
+
+        if (jsonBlocks.length !== 1) {
+            throw new Error(`Expected exactly one JSON code block in ${instructionsFilePath}, but found ${jsonBlocks.length}.`);
+        }
+
+        const jsonBlockContent = jsonBlocks[0].content;
+        let rawJson = null;
+        try {
+            rawJson = JSON.parse(jsonBlockContent);
+        } catch (parseError) {
+            console.error(`Error parsing JSON content from ${instructionsFilePath}: ${parseError.message}`);
+            return null;
+        }
+
+        const schema = {
+            type: 'object',
+            description: rawJson.description,
+            properties: {},
+            required: []
+        };
+
+        const metadataProperties = rawJson?.extracted_metadata;
+
+        if (metadataProperties && typeof metadataProperties === 'object') {
+            for (const fieldName in metadataProperties) {
+                if (Object.hasOwnProperty.call(metadataProperties, fieldName)) {
+                    const rawValue = metadataProperties[fieldName];
+                    const fieldSchema = deduceSchemaType(rawValue, fieldName);
+                    const description = rawValue.match(/^\[\w+: ([^\]]+)\]/)?.[1] || '';
+
+                    schema.properties[fieldName] = {
+                        ...fieldSchema,
+                        description,
+                        title: fieldName.replace(/_/g, ' ').replace(/\b\w/g, l => l.toUpperCase())
+                    };
+                }
+            }
+        } else {
+            console.warn(`Warning: Could not find 'extracted_metadata' object in JSON block from ${instructionsFilePath}. Schema will be empty.`);
+        }
+
+        return schema;
+
+    } catch (error) {
+        if (error.code === 'ENOENT') {
+            console.warn(`Analyzer instructions file not found: ${instructionsFilePath}`);
+            return null;
+        } else {
+            console.error(`Error retrieving or processing schema for analyzer ${analyzerId}: ${error.message}`);
+            throw error;
+        }
+    }
+}
+
+module.exports = {
+    getAnalyzerSchema,
+    deduceSchemaType
+};

package/src/CodeBlockUtils/continuationUtils.js

@@ -1,4 +1,4 @@
-/**
+/*
  * Component: CodeBlockUtils Continuation Utilities
  * Block-UUID: 6fdf5c7d-4def-42a1-bc88-0312f6002cfc
  * Parent-UUID: 6322afcd-2e5e-425a-9a43-4c72c887f668
@@ -165,8 +165,8 @@ Example of the START of your response:
 \`\`\`${language}
 /**
  * Component: ${componentName}
-* Block-UUID: 01147ddf-320f-498a-a744-198d42a9d2ee
-* Parent-UUID: e4c0d839-ea17-467d-a0cc-d269d1dbc404
+ * Block-UUID: 01147ddf-320f-498a-a744-198d42a9d2ee
+ * Parent-UUID: e4c0d839-ea17-467d-a0cc-d269d1dbc404
  * Version: ${nextVersion}
  * Description: ${description}
  * Language: ${language}

package/src/ConfigUtils.js

@@ -0,0 +1,86 @@
+/*
+ * Component: Config Utilities
+ * Block-UUID: 89016e46-9898-42f0-bef4-564e442cfaf3
+ * Parent-UUID: N/A
+ * Version: 1.0.0
+ * Description: Provides utility functions for loading and accessing application configuration from data/chats.json.
+ * Language: JavaScript
+ * Created-at: 2025-08-28T17:46:26.948Z
+ * Authors: Gemini 2.5 Flash (v1.0.0)
+ */
+
+
+const fs = require('fs').promises;
+
+/**
+ * Loads and parses the application configuration from the specified JSON file.
+ *
+ * @param {string} filePath - The absolute path to the data/chats.json file.
+ * @returns {Promise<Object>} A promise that resolves with the parsed configuration object.
+ * @throws {Error} If the file cannot be read or parsed.
+ */
+async function loadConfig(filePath) {
+    try {
+        const fileContent = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(fileContent);
+    } catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Configuration file not found at: ${filePath}`);
+        }
+        throw new Error(`Failed to load or parse configuration from ${filePath}: ${error.message}`);
+    }
+}
+
+/**
+ * Retrieves the configuration details for a specific LLM provider.
+ *
+ * @param {Object} config - The loaded configuration object.
+ * @param {string} providerName - The name of the LLM provider (e.g., "Google", "Anthropic").
+ * @returns {Object|null} The provider's configuration object or null if not found.
+ */
+function getProviderConfig(config, providerName) {
+    if (!config || !config.providers || !Array.isArray(config.providers)) {
+        return null;
+    }
+    return config.providers.find(p => p.name === providerName) || null;
+}
+
+/**
+ * Finds the specific modelId and other details for a given user-friendly modelName and providerName.
+ *
+ * @param {Object} config - The loaded configuration object.
+ * @param {string} modelName - The user-friendly name of the model (e.g., "Gemini 2.5 Flash").
+ * @param {string} providerName - The name of the provider associated with that model.
+ * @returns {Object|null} An object containing modelId, maxOutputTokens, and other provider-specific model details, or null if not found.
+ */
+function getModelProviderDetails(config, modelName, providerName) {
+    if (!config || !config.models || !Array.isArray(config.models)) {
+        return null;
+    }
+
+    const modelEntry = config.models.find(m => m.name === modelName);
+    if (!modelEntry || !modelEntry.providers || !Array.isArray(modelEntry.providers)) {
+        return null;
+    }
+
+    return modelEntry.providers.find(p => p.name === providerName) || null;
+}
+
+/**
+ * Retrieves the environment variable name (e.g., "GEMINI_API_KEY") for the API key of a specific provider.
+ *
+ * @param {Object} config - The loaded configuration object.
+ * @param {string} providerName - The name of the LLM provider.
+ * @returns {string|null} The name of the environment variable that holds the API key, or null if not found.
+ */
+function getApiKeyName(config, providerName) {
+    const providerConfig = getProviderConfig(config, providerName);
+    return providerConfig ? providerConfig.apiKeyName : null;
+}
+
+module.exports = {
+    loadConfig,
+    getProviderConfig,
+    getModelProviderDetails,
+    getApiKeyName
+};