minovative-mind-cli 2.5.1 → 2.6.0

package/dist/services/agent/syntaxAgent.js

@@ -1,8 +1,67 @@
 import { ProxyChatSession } from '../ai.js';
 import { GEMINI_MODELS, MAX_OUTPUT_TOKENS } from '../../utils/config.js';
+import { localValidate } from '../../utils/localSyntaxValidator.js';
+/**
+ * Extracts a numeric character position from a syntax error message if present.
+ */
+function parseErrorPosition(errorMsg) {
+    if (!errorMsg)
+        return null;
+    const match = errorMsg.match(/position\s+(\d+)/i);
+    if (match && match[1]) {
+        const pos = parseInt(match[1], 10);
+        return isNaN(pos) ? null : pos;
+    }
+    return null;
+}
+/**
+ * Extracts a surrounding line window around a given character position in file content.
+ */
+function getSnippetWindow(content, pos, contextLines = 40) {
+    if (pos < 0 || pos >= content.length)
+        return null;
+    const lines = content.split('\n');
+    let currentPos = 0;
+    let targetLine = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const lineLen = lines[i].length + 1; // +1 for '\n'
+        if (currentPos + lineLen > pos) {
+            targetLine = i;
+            break;
+        }
+        currentPos += lineLen;
+    }
+    const startLine = Math.max(0, targetLine - contextLines);
+    const endLine = Math.min(lines.length - 1, targetLine + contextLines);
+    let startPos = 0;
+    for (let i = 0; i < startLine; i++) {
+        startPos += lines[i].length + 1;
+    }
+    const snippetLines = lines.slice(startLine, endLine + 1);
+    const snippet = snippetLines.join('\n');
+    const endPos = startPos + snippet.length;
+    return {
+        startPos,
+        endPos,
+        startLine: startLine + 1,
+        endLine: endLine + 1,
+        snippet,
+    };
+}
+/**
+ * Strips markdown code fences from AI model output.
+ */
+function cleanOutput(raw) {
+    let output = raw.trim();
+    if (output.startsWith('```')) {
+        output = output.replace(/^```[a-zA-Z]*\n?/, '').replace(/\n?```$/, '').trim();
+    }
+    return output;
+}
 /**
  * Validates file content and attempts to fix syntax errors.
  * Uses GEMINI_MODELS.FLASH to perform language-agnostic syntax repair.
+ * Utilizes local validation error context and windowed snippet repair for large files.
  *
  * @param content The file content to validate.
  * @param filePath The path of the file being validated.
@@ -10,43 +69,198 @@ import { GEMINI_MODELS, MAX_OUTPUT_TOKENS } from '../../utils/config.js';
  * @returns The fixed content, or undefined if it was completely valid or couldn't be fixed.
  */
 export async function validateAndFixSyntax(content, filePath, error) {
-    const model = GEMINI_MODELS.FLASH; // Always use flash for syntax checking for speed
-    const systemInstruction = `
+    // 1. First run fast local validation to check if content is already valid or gather error details
+    const localResult = localValidate(filePath, content);
+    if (localResult.isValid && !error) {
+        return undefined; // Content is already syntactically valid
+    }
+    const effectiveError = error || localResult.error || 'Syntax validation failed';
+    const model = GEMINI_MODELS.FLASH;
+    // 2. Determine error position for targeted window snippet repair on large files
+    const errorPos = parseErrorPosition(effectiveError) || parseErrorPosition(localResult.error);
+    const isLargeFile = content.length > 8000 || content.split('\n').length > 200;
+    if (isLargeFile && errorPos !== null) {
+        const win = getSnippetWindow(content, errorPos, 45);
+        if (win) {
+            const snippetSystemInstruction = `
+<identity>
+You are an expert software engineer and syntax repair agent.
+Your job is to fix syntax errors in source code snippets extracted from large files.
+</identity>
+
+<rules>
+1. Fix ONLY the syntax error described in the provided error context.
+2. Return ONLY the fully corrected code snippet.
+3. Do NOT include markdown code blocks (like \`\`\`typescript), explanations, or conversational text.
+4. Keep all original formatting, variable names, logic, and comments intact outside the syntax fix.
+</rules>
+`;
+            const snippetChat = new ProxyChatSession(model, snippetSystemInstruction, [], {
+                maxOutputTokens: MAX_OUTPUT_TOKENS,
+                temperature: 0.1,
+            });
+            const snippetPrompt = `File Path: ${filePath}
+Line Range: Lines ${win.startLine} to ${win.endLine} (Error near position ${errorPos})
+Syntax Error Details: ${effectiveError}
+
+Code Snippet to Repair:
+${win.snippet}
+
+Please fix the syntax error in the snippet above and return ONLY the raw repaired code snippet:`;
+            try {
+                const result = await snippetChat.sendMessage(snippetPrompt);
+                const repairedSnippet = cleanOutput(result.response.text());
+                if (repairedSnippet && repairedSnippet !== win.snippet) {
+                    const candidateContent = content.slice(0, win.startPos) + repairedSnippet + content.slice(win.endPos);
+                    const candidateCheck = localValidate(filePath, candidateContent);
+                    if (candidateCheck.isValid) {
+                        return candidateContent;
+                    }
+                }
+            }
+            catch (err) {
+                // Snippet repair failed or encountered API error; continue to full file repair fallback
+            }
+        }
+    }
+    // 3. Full file repair strategy (for smaller files or when snippet repair was insufficient)
+    const fullSystemInstruction = `
 <identity>
 You are an expert compiler and syntax validator.
-Your sole job is to read source code and verify its syntax.
+Your sole job is to read source code and verify or repair its syntax.
 </identity>
 
 <rules>
-1. If the provided code has NO syntax errors (e.g., balanced braces, correct language keywords, complete statements), you MUST respond exactly with the word: VALID
-2. If the code has syntax errors (e.g., a missing closing bracket, dangling parenthesis, unfinished string literal), you must fix the code.
-3. If you fix the code, you MUST output ONLY the completely fixed file content. Do not include any explanations, markdown code blocks (like \`\`\`typescript), or conversational text.
-4. Keep the original formatting and comments intact. Only fix the syntax.
+1. If the provided code has NO syntax errors (e.g., balanced braces, correct language keywords, complete statements), respond exactly with: VALID
+2. If the code has syntax errors (e.g., missing closing bracket, dangling parenthesis, unfinished string literal), fix the syntax.
+3. Pay close attention to the provided Local Validator Error Context to locate and fix the specific issue.
+4. Output ONLY the completely fixed file content. Do NOT include any explanations, markdown code blocks (like \`\`\`typescript), or conversational text.
+5. Keep original formatting, comments, and logic intact. Only fix syntax defects.
 </rules>
 `;
-    const chat = new ProxyChatSession(model, systemInstruction, [], // No tools needed
-    {
+    const fullChat = new ProxyChatSession(model, fullSystemInstruction, [], {
         maxOutputTokens: MAX_OUTPUT_TOKENS,
-        temperature: 0.1, // Very low temp for strict syntax work
+        temperature: 0.1,
     });
-    let prompt = `File Path: ${filePath}\n\nContent:\n${content}`;
-    if (error) {
-        prompt += `\n\nLocal Validator Error: ${error}`;
-    }
+    const fullPrompt = `File Path: ${filePath}
+
+Local Validator Error Context:
+${effectiveError}
+
+Content:
+${content}`;
     try {
-        const result = await chat.sendMessage(prompt);
-        let output = result.response.text().trim();
-        // Clean up potential markdown blocks if the model ignored the rule
-        if (output.startsWith('\`\`\`')) {
-            output = output.replace(/^\`\`\`[a-zA-Z]*\n/, '').replace(/\n\`\`\`$/, '').trim();
+        const result = await fullChat.sendMessage(fullPrompt);
+        const output = cleanOutput(result.response.text());
+        if (output === 'VALID' || output === '' || output === content) {
+            return undefined;
         }
-        if (output === 'VALID' || output === '') {
-            return undefined; // No fix needed
+        // Verify the repaired full content is syntactically valid before returning
+        const postValidation = localValidate(filePath, output);
+        if (postValidation.isValid) {
+            return output;
         }
-        return output;
+        return undefined;
     }
     catch (err) {
-        // If the AI fails (e.g., network error), we return undefined to fall back to the main agent loop
         return undefined;
     }
 }
+/**
+ * Performs AI-assisted fuzzy search matching and edit application using Gemini Flash.
+ * Invoked when deterministic local fuzzy matchers fail to locate a search target block
+ * due to whitespace variations, formatting shifts, comment differences, or minor code drift.
+ *
+ * @param fileContent The current full file content.
+ * @param searchContent The search target block that local matchers failed to locate.
+ * @param replaceContent The replacement text block to insert in place of the target block.
+ * @param filePath The path of the file being edited (used for syntax and language context).
+ * @param options Optional configuration including custom model or syntax validation toggles.
+ * @returns A promise resolving to an AIFuzzyMatchResult.
+ */
+export async function aiFuzzyMatch(fileContent, searchContent, replaceContent, filePath, options = {}) {
+    if (!fileContent || !searchContent) {
+        return {
+            success: false,
+            error: 'File content and search content must not be empty.',
+        };
+    }
+    const model = options.model || GEMINI_MODELS.FLASH;
+    const shouldValidateSyntax = options.validateSyntax !== false;
+    const systemInstruction = `
+<identity>
+You are an expert software engineer and code editing agent.
+Your primary job is to perform fuzzy search matching and replacement on source code when exact or deterministic matchers fail.
+</identity>
+
+<rules>
+1. Analyze the provided File Content and locate the section that semantically and structurally matches the Search Target, even if there are variations in indentation, whitespace, line breaks, comments, or minor refactoring.
+2. Replace that target section with the Replacement Content.
+3. Preserve all surrounding code, formatting, comments, and imports exactly as they appear outside the target section.
+4. Do NOT introduce any extra changes, refactoring, or formatting cleanups outside the specified edit location.
+5. If the Search Target cannot be located anywhere in the File Content with reasonable confidence, respond with exactly: UNMATCHED
+6. Output ONLY the updated full file content (or UNMATCHED). Do NOT wrap your output in markdown code blocks (like \`\`\`typescript), and do NOT include any explanations or conversational text.
+</rules>
+`;
+    const chat = new ProxyChatSession(model, systemInstruction, [], {
+        maxOutputTokens: MAX_OUTPUT_TOKENS,
+        temperature: 0.1,
+    });
+    const prompt = `File Path: ${filePath}
+
+Search Target (Block to locate in file):
+${searchContent}
+
+Replacement Content (Block to insert in place of Search Target):
+${replaceContent}
+
+File Content:
+${fileContent}`;
+    try {
+        const response = await chat.sendMessage(prompt);
+        const rawOutput = response.response.text();
+        const output = cleanOutput(rawOutput);
+        if (output === 'UNMATCHED' || !output || output === fileContent) {
+            return {
+                success: false,
+                error: `AI fuzzy search matcher could not locate search target block in ${filePath}.`,
+            };
+        }
+        let finalContent = output;
+        if (shouldValidateSyntax) {
+            const valResult = localValidate(filePath, finalContent);
+            if (!valResult.isValid) {
+                // Attempt automatic syntax repair on AI output if local validation detected syntax error
+                const repaired = await validateAndFixSyntax(finalContent, filePath, valResult.error);
+                if (repaired) {
+                    finalContent = repaired;
+                }
+            }
+        }
+        return {
+            success: true,
+            content: finalContent,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: `AI fuzzy search error: ${err?.message || String(err)}`,
+        };
+    }
+}
+/**
+ * Convenience wrapper around aiFuzzyMatch that returns the updated file content string if successful,
+ * or undefined if fuzzy matching and replacement failed.
+ *
+ * @param fileContent The current full file content.
+ * @param searchContent The search target block that local matchers failed to locate.
+ * @param replaceContent The replacement text block to insert in place of the target block.
+ * @param filePath The path of the file being edited.
+ * @param options Optional configuration options.
+ * @returns The updated file content string if successful, or undefined if failed.
+ */
+export async function aiFuzzySearchAndReplace(fileContent, searchContent, replaceContent, filePath, options) {
+    const result = await aiFuzzyMatch(fileContent, searchContent, replaceContent, filePath, options);
+    return result.success ? result.content : undefined;
+}

package/dist/services/agent/toolLoop.js

@@ -70,7 +70,16 @@ export function formatToolCall(name, args) {
         write_file: () => `: ${formatPath(String(args.filePath))}`,
         modify_file: () => `: ${formatPath(String(args.filePath))}`,
         list_directory: () => `: ${formatPath(String(args.dirPath ?? '.'))}`,
-        run_command: () => `: ${pc.yellow(String(args.command))}`,
+        run_command: () => {
+            const raw = String(args.command);
+            // Collapse to first line and truncate for readability
+            const firstLine = raw.split('\n')[0].trim();
+            const MAX_CMD_DISPLAY = 80;
+            const truncated = firstLine.length > MAX_CMD_DISPLAY
+                ? firstLine.substring(0, MAX_CMD_DISPLAY) + '...'
+                : (raw.includes('\n') ? firstLine + '...' : firstLine);
+            return `: ${pc.yellow(truncated)}`;
+        },
         grep_search: () => `: ${pc.magenta(String(args.pattern))}`,
         delete_file: () => `: ${pc.red(String(args.filePath))}`,
         rename_file: () => `: ${formatPath(String(args.sourcePath))} -> ${formatPath(String(args.targetPath))}`,

package/dist/services/agent/types.d.ts

@@ -16,6 +16,7 @@ export interface SlashCommandContext {
         totalTokens: number;
         totalInputTokens: number;
         totalOutputTokens: number;
+        totalCreditsUsed: number;
         latestUsageMetadata?: any;
         previousUsageMetadata?: any;
         modelUsageCounts?: Record<string, number>;

package/dist/services/agent-tools.d.ts

@@ -1,12 +1,30 @@
+/**
+ * @file agent-tools.ts
+ * @description Implements tool declarations, approval state management, ignore rule parser,
+ * atomic file operations, search/grep engines, dependency tracer, scratchpad script runner,
+ * and central tool dispatcher used by the Minovative Mind AI agents.
+ */
 import { type FunctionDeclaration } from '@google/generative-ai';
+/**
+ * Represents the structured result returned by any agent tool execution.
+ */
 export interface ToolResult {
+    /** Optional error message if the tool execution failed. */
     error?: string;
+    /** Standard textual output or formatted content produced by the tool. */
     output: string;
+    /** Optional binary or specialized inline data (such as PDFs) attached to the result. */
     inlineData?: {
         mimeType: string;
         data: string;
     };
 }
+/**
+ * Returns the list of available function declarations for Gemini function calling.
+ *
+ * @param options - Configuration options such as `isExecutionAgent`.
+ * @returns An array of Google Generative AI `FunctionDeclaration` objects.
+ */
 export declare function getToolDeclarations(options?: {
     isExecutionAgent?: boolean;
 }): FunctionDeclaration[];
@@ -15,27 +33,164 @@ export declare function getToolDeclarations(options?: {
  * every tool the agent can invoke. Passed to the model at init.
  */
 export declare const toolDeclarations: FunctionDeclaration[];
+/**
+ * Defines the command execution approval mode.
+ * - `ask`: Prompts the user before executing shell commands.
+ * - `skip-once`: Automatically approves the next shell command, then reverts to `ask`.
+ * - `skip-all`: Automatically approves all subsequent shell commands in the session.
+ */
 export type ApprovalMode = 'ask' | 'skip-once' | 'skip-all';
+/**
+ * Retrieves the current command execution approval mode.
+ *
+ * @returns The active {@link ApprovalMode}.
+ */
 export declare function getApprovalMode(): ApprovalMode;
+/**
+ * Sets the command execution approval mode.
+ *
+ * @param mode - The {@link ApprovalMode} to set.
+ */
 export declare function setApprovalMode(mode: ApprovalMode): void;
+/**
+ * Checks whether sub-agents are currently enabled.
+ *
+ * @returns `true` if sub-agents are enabled, `false` otherwise.
+ */
 export declare function isSubAgentsEnabled(): boolean;
+/**
+ * Enables or disables sub-agents.
+ *
+ * @param enabled - Boolean indicating whether sub-agents should be enabled.
+ */
 export declare function setSubAgentsEnabled(enabled: boolean): void;
 /**
  * If set to 'skip-once', reverts to 'ask' after a single command is run.
  */
 export declare function consumeSkipOnce(): void;
+/**
+ * Reads the contents of a file at the given relative or absolute path, supporting text files,
+ * native PDF parsing, SQLite database schema dumping, Jupyter Notebook (.ipynb) cell extraction,
+ * and CSV-to-Markdown table formatting.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param filePath - Relative path to the target file (or `@alias/` prefixed path).
+ * @param startLine - Optional 1-indexed starting line number.
+ * @param endLine - Optional 1-indexed ending line number.
+ * @param targetElements - Optional array of specific symbol or function names to extract.
+ * @returns A promise resolving to a {@link ToolResult} containing the file content or error details.
+ */
 export declare function readFile(workspaceRoot: string, filePath: string, startLine?: number, endLine?: number, targetElements?: string[]): Promise<ToolResult>;
+/**
+ * Creates a new file or completely overwrites an existing file with the provided content,
+ * performing local syntax validation and iterative AI syntax auto-correction if validation fails.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param filePath - Relative path to the target file.
+ * @param content - The complete content to write.
+ * @returns A promise resolving to a {@link ToolResult} indicating success or failure.
+ */
 export declare function writeFile(workspaceRoot: string, filePath: string, content: string): Promise<ToolResult>;
+/**
+ * Deletes a file from the filesystem and records the deletion in the change logger.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param filePath - Relative path to the file to delete.
+ * @returns A promise resolving to a {@link ToolResult} indicating success or failure.
+ */
 export declare function deleteFile(workspaceRoot: string, filePath: string): Promise<ToolResult>;
+/**
+ * Moves or renames a file from `sourcePath` to `targetPath`.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param sourcePath - Original relative file path.
+ * @param targetPath - New destination relative file path.
+ * @returns A promise resolving to a {@link ToolResult} indicating success or failure.
+ */
 export declare function renameFile(workspaceRoot: string, sourcePath: string, targetPath: string): Promise<ToolResult>;
+/**
+ * Performs one or multiple targeted search-and-replace edits on a file, utilizing deterministic fuzzy matching,
+ * fallback AI fuzzy matching, syntax validation, and atomic writes.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param filePath - Relative path to the target file.
+ * @param edits - An array of edit objects containing `searchContent` and `replaceContent`.
+ * @returns A promise resolving to a {@link ToolResult} indicating success or failure.
+ */
 export declare function modifyFile(workspaceRoot: string, filePath: string, edits: Array<{
     searchContent: string;
     replaceContent: string;
 }>): Promise<ToolResult>;
+/**
+ * Lists files and subdirectories within a directory, returning a recursive ASCII tree structure
+ * while respecting ignore rules and excluded extensions.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param dirPath - Relative path to the target directory.
+ * @param maxDepth - Maximum recursion depth (defaults to 3).
+ * @returns A promise resolving to a {@link ToolResult} containing the formatted tree output.
+ */
 export declare function listDirectory(workspaceRoot: string, dirPath: string, maxDepth?: number): Promise<ToolResult>;
+/**
+ * Executes a shell command within the workspace root with a timeout and buffer limit.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param command - The shell command string to execute.
+ * @param abortSignal - Optional AbortSignal to cancel execution.
+ * @returns A promise resolving to a {@link ToolResult} containing stdout/stderr or an error.
+ */
 export declare function runCommand(workspaceRoot: string, command: string, abortSignal?: AbortSignal): Promise<ToolResult>;
-export declare function grepSearch(workspaceRoot: string, pattern: string, fileGlob?: string, abortSignal?: AbortSignal): Promise<ToolResult>;
+/**
+ * Performs a grep text or regular expression search across files in the workspace.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param pattern - The search text or regex pattern.
+ * @param fileGlob - Optional file glob to restrict matched files.
+ * @param fixedStrings - If true, treats the pattern as a literal fixed string.
+ * @param dirPath - Optional subdirectory path to restrict the search.
+ * @param abortSignal - Optional AbortSignal to cancel execution.
+ * @returns A promise resolving to a {@link ToolResult} containing matching lines and file paths.
+ */
+export declare function grepSearch(workspaceRoot: string, pattern: string, fileGlob?: string, fixedStrings?: boolean, dirPath?: string, abortSignal?: AbortSignal): Promise<ToolResult>;
+/**
+ * Traces file dependencies (forward imports and reverse dependants) to determine the blast radius of changes.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param filePath - Relative path to the file to trace.
+ * @param direction - Trace direction (`'both'`, `'forward'`, or `'reverse'`).
+ * @param maxDepth - Maximum recursion depth (defaults to 3).
+ * @returns A promise resolving to a {@link ToolResult} containing formatted dependency results.
+ */
 export declare function traceDependencies(workspaceRoot: string, filePath: string, direction?: string, maxDepth?: number): Promise<ToolResult>;
+/**
+ * Finds files modified within the workspace recently (within a specified time window).
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param dirPath - Subdirectory path to search from (defaults to `'.'`).
+ * @param minutes - Time window in minutes (defaults to 60).
+ * @param maxDepth - Maximum directory traversal depth (defaults to 5).
+ * @returns A promise resolving to a {@link ToolResult} containing recently modified files.
+ */
 export declare function findRecentChanges(workspaceRoot: string, dirPath?: string, minutes?: number, maxDepth?: number): Promise<ToolResult>;
+/**
+ * Writes a disposable scratchpad script to a temporary file, executes it using the specified runtime,
+ * and returns standard output and standard error.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param language - Runtime language (`'node'`, `'ts-node'`, `'python'`, `'bash'`, `'go'`, or `'rust'`).
+ * @param code - The exact script source code to execute.
+ * @param abortSignal - Optional AbortSignal to cancel execution.
+ * @returns A promise resolving to a {@link ToolResult} containing execution output.
+ */
 export declare function runDebugScript(workspaceRoot: string, language: string, code: string, abortSignal?: AbortSignal): Promise<ToolResult>;
+/**
+ * Central tool dispatcher that resolves multi-workspace paths, executes the requested tool
+ * with the provided arguments, records metrics, and returns the standardized {@link ToolResult}.
+ *
+ * @param workspaceRoot - Absolute path to the primary workspace root directory.
+ * @param toolName - Name of the tool to invoke.
+ * @param args - Key-value map of tool arguments.
+ * @param abortSignal - Optional AbortSignal to cancel tool execution.
+ * @returns A promise resolving to a {@link ToolResult}.
+ */
 export declare function executeTool(workspaceRoot: string, toolName: string, args: Record<string, unknown>, abortSignal?: AbortSignal): Promise<ToolResult>;