devsplain 2.2.1 → 2.2.3

package/bin/cli.js

@@ -10,7 +10,7 @@ const { execSync } = require('child_process');
 let rl;
 let askQuestion;
 
-// Determines whether the current Git repository has uncommitted changes [ds]
+// Checks if the Git repository is dirty [ds]
 function isGitDirty() {
     try {
         const gitDir = execSync('git rev-parse --is-inside-work-tree', { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim();
@@ -23,7 +23,7 @@ function isGitDirty() {
     return false;
 }
 
-// Checks whether a given line of code is inside a string literal [ds]
+// Determines if a line is inside a string literal [ds]
 function isLineInsideString(lines, targetLineIndex, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     const isHTML = ['.html', '.vue', '.svelte'].includes(ext.toLowerCase());
@@ -231,12 +231,13 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
         if (resetsAtLineEnd) {
             inSingle = false;
             inDouble = false;
+            inRegex = false;
         }
     }
     return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble || inCppRawString || inRegex;
 }
 
-// Analyzes comments within a given list of code lines [ds]
+// Analyzes comments in the given lines of code [ds]
 function analyzeComments(lines, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     const isHTML = ['.html', '.vue', '.svelte'].includes(ext.toLowerCase());
@@ -455,6 +456,7 @@ function analyzeComments(lines, ext = '') {
         if (resetsAtLineEnd) {
             inSingle = false;
             inDouble = false;
+            inRegex = false;
         }
         const isEntirelyInsideBlock = isInsideBlockStart && (inBlockJS || inBlockHTML || (commentStartIndex === -1));
         let isPureComment = false;
@@ -477,7 +479,7 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-// Inserts or removes comments from code based on the specified mode [ds]
+// Splices comments into the provided data [ds]
 function spliceComments(data, comments, mode = 'default', ext = '') {
     const hasCRLF = data.includes('\r\n');
     const lineEnding = hasCRLF ? '\r\n' : '\n';
@@ -663,6 +665,33 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     const filteredText = filtered.map(line => line.text);
     const filteredIndices = filtered.map(line => line.originalIndex);
 
+    // Validate that all inserted lines (originalIndex === -1) are valid comments or empty lines [ds]
+    const insertedLines = annotated.filter(line => line.originalIndex === -1);
+    let inInsertedBlock = false;
+    for (const item of insertedLines) {
+        const trimmed = item.text.trim();
+        if (!trimmed) continue;
+        if (inInsertedBlock) {
+            if (trimmed.includes('*/') || trimmed.includes('-->')) {
+                inInsertedBlock = false;
+            }
+            continue;
+        }
+        const isValidComment = 
+            trimmed.startsWith('//') || 
+            trimmed.startsWith('/*') || 
+            trimmed.startsWith('*') || 
+            trimmed.startsWith('#') || 
+            trimmed.startsWith('<!--') || 
+            trimmed.startsWith('--');
+        if (!isValidComment) {
+            throw new Error(`Safety Assertion Failed: Refused to insert non-comment code: "${trimmed}"`);
+        }
+        if ((trimmed.startsWith('/*') && !trimmed.includes('*/')) || (trimmed.startsWith('<!--') && !trimmed.includes('-->'))) {
+            inInsertedBlock = true;
+        }
+    }
+
     const textEqual = filteredText.every((text, idx) => {
         const origIdx = filteredIndices[idx];
         const originalLine = originalLines[origIdx];
@@ -710,14 +739,13 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     }
 
     if (!textEqual || !indicesSequential) {
-        console.error("\nSafety Assertion Failed: Spliced code does not match original code minus comments!");
-        process.exit(1);
+        throw new Error("Safety Assertion Failed: Spliced code does not match original code minus comments!");
     }
 
     return annotated.map(line => line.text).join(lineEnding);
 }
 
-// Runs the command-line interface for the application [ds]
+// Runs the CLI interface for the application [ds]
 async function runCLI() {
     rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
@@ -744,6 +772,7 @@ Options:
   --base-url <url>    Override base URL for custom APIs
   --config            Force run the configuration setup wizard
   --setup-hook        Install Git pre-commit and post-commit hooks in repository
+  --remove-hook       Remove devsplain-installed Git hooks from repository
   --help, -h          Show this help message
   --version, -v       Show version information
 `);
@@ -767,11 +796,18 @@ Options:
 
     if (args.includes('--setup-hook')) {
         rl.close();
-        const installHooks = require('./setup-hook.js');
+        const { installHooks } = require('./setup-hook.js');
         await installHooks();
         return;
     }
 
+    if (args.includes('--remove-hook')) {
+        rl.close();
+        const { removeHooks } = require('./setup-hook.js');
+        await removeHooks();
+        return;
+    }
+
     const getArgValue = (flag) => {
         const index = args.indexOf(flag);
         if (index !== -1 && index + 1 < args.length) {
@@ -810,7 +846,7 @@ Options:
     const hasOverwriteFlag = args.includes('--overwrite');
     const hasKeepFlag = args.includes('--keep');
 
-    if (process.env.NODE_ENV !== 'test' && isGitDirty() && !isForce) {
+    if (process.env.NODE_ENV !== 'test' && isGitDirty() && !isForce && !isDryRun) {
         console.error("Error: Git working tree is dirty. Please commit or stash your changes, or use --force to bypass this check.");
         rl.close();
         process.exit(1);
@@ -863,9 +899,10 @@ Options:
 
     function isPathIgnored(targetPath) {
         const filename = path.basename(targetPath);
+        const relPath = path.relative(process.cwd(), targetPath).replace(/\\/g, '/');
         for (const pattern of allIgnored) {
             const cleanPattern = pattern.replace(/\/$/, '').replace(/\\$/, '');
-            if (filename === cleanPattern) return true;
+            if (filename === cleanPattern || relPath === cleanPattern || relPath.startsWith(cleanPattern + '/')) return true;
             if (pattern.startsWith('*') && filename.endsWith(pattern.slice(1))) return true;
         }
         return false;
@@ -891,7 +928,7 @@ Options:
             const validExtensions = [
                 '.js', '.jsx', '.ts', '.tsx', '.html', '.css', '.scss', '.vue', '.svelte',
                 '.py', '.java', '.c', '.cpp', '.cs', '.go', '.rb', '.php', '.rs', 
-                '.swift', '.kt', '.dart', '.sh'
+                '.swift', '.kt', '.dart', '.sh', '.sql'
             ];
 
             if (!validExtensions.includes(ext)) {

package/bin/post-commit.js

@@ -1,4 +1,4 @@
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const { spliceComments } = require('./cli');
@@ -30,7 +30,7 @@ try {
     }
 
     // Get a list of changed files in the last commit [ds]
-    const changedFilesStr = execSync('git diff-tree --no-commit-id --name-only -r HEAD', { encoding: 'utf8' }).trim();
+    const changedFilesStr = execSync('git diff-tree --no-commit-id --name-only -r --root HEAD', { encoding: 'utf8' }).trim();
     if (!changedFilesStr) {
         process.exit(0);
     }
@@ -40,7 +40,7 @@ try {
     const validExtensions = [
         '.js', '.jsx', '.ts', '.tsx', '.html', '.css', '.scss', '.vue', '.svelte',
         '.py', '.java', '.c', '.cpp', '.cs', '.go', '.rb', '.php', '.rs',
-        '.swift', '.kt', '.dart', '.sh'
+        '.swift', '.kt', '.dart', '.sh', '.sql'
     ];
 
     /** Filter function to determine which files to auto-comment [ds] */
@@ -97,13 +97,13 @@ try {
         // Log and attempt to auto-comment the current file [ds]
         console.log(`[devsplain] Automatically commenting file: ${file}`);
         try {
-            let extraFlags = '';
-            if (process.env.DS_OVER) extraFlags += ' --overwrite';
-            if (process.env.DS_KEEP) extraFlags += ' --keep';
-
-            // Construct the command to run the auto-commenting CLI [ds]
             const cliPath = path.join(__dirname, 'cli.js');
-            execSync(`node "${cliPath}" "${file}" --force${modeFlag}${extraFlags}`, { stdio: 'inherit' });
+            const cliArgs = [cliPath, file, '--force'];
+            if (modeFlag.trim()) cliArgs.push(modeFlag.trim());
+            if (process.env.DS_OVER) cliArgs.push('--overwrite');
+            if (process.env.DS_KEEP) cliArgs.push('--keep');
+
+            execFileSync(process.execPath, cliArgs, { stdio: 'inherit' });
             commentedAny = true;
             successfullyCommentedFiles.push(file);
         } catch (err) {
@@ -115,7 +115,7 @@ try {
     if (commentedAny) {
         for (const file of successfullyCommentedFiles) {
             try {
-                execSync(`git add "${file}"`);
+                execFileSync('git', ['add', file]);
             } catch (addErr) {}
         }
         

package/bin/setup-hook.js

@@ -3,7 +3,7 @@ const path = require('path');
 const { execSync } = require('child_process');
 const readline = require('readline');
 
-/** Installs Git hooks and configures commit settings [ds] */
+// Installs Git hooks for automatic comment generation [ds]
 async function installHooks() {
     try {
         const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
@@ -14,7 +14,7 @@ async function installHooks() {
         }
 
         let modeChoice = '1';
-        // Check if process is run in a TTY environment [ds]
+        // Prompt user for commenting mode if running in a TTY [ds]
         if (process.stdout.isTTY) {
             const rl = readline.createInterface({
                 input: process.stdin,
@@ -22,13 +22,13 @@ async function installHooks() {
             });
             const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
-            // Prompt user to select the default commenting mode [ds]
+            // Display commenting mode options to the user [ds]
             console.log('\nSelect default commenting mode for Git commits:');
             console.log('1. Balanced (mix of JSDoc and sparse inline comments)');
             console.log('2. Light (JSDoc block comments above functions only)');
             console.log('3. Full (aggressive inline commenting)');
             
-            // Validate user input for commenting mode [ds]
+            // Loop until a valid mode choice is selected [ds]
             while (true) {
                 const answer = (await askQuestion('Select (1-3, default: 1): ')).trim();
                 if (answer === '' || ['1', '2', '3'].includes(answer)) {
@@ -40,7 +40,7 @@ async function installHooks() {
             rl.close();
         }
 
-        // Determine mode arguments based on user choice [ds]
+        // Determine mode arguments based on user selection [ds]
         let modeArgs = '';
         if (modeChoice === '2') {
             modeArgs = ' --light';
@@ -48,7 +48,7 @@ async function installHooks() {
             modeArgs = ' --full';
         }
 
-        // Define the pre-commit hook script [ds]
+        // Create pre-commit hook script [ds]
         const preCommitHookPath = path.join(hooksDir, 'pre-commit');
         const preCommitContent = `#!/bin/sh
 # devsplain native pre-commit hook
@@ -57,63 +57,144 @@ if [ -f package.json ] && grep -q '"test"' package.json 2>/dev/null; then
   npm test || exit 1
 fi
 `;
-        // Write the pre-commit hook to the Git hooks directory [ds]
-        fs.writeFileSync(preCommitHookPath, preCommitContent);
+        // Write pre-commit hook safely [ds]
+        if (fs.existsSync(preCommitHookPath)) {
+            const existing = fs.readFileSync(preCommitHookPath, 'utf8');
+            if (!existing.includes('# devsplain native pre-commit hook')) {
+                fs.appendFileSync(preCommitHookPath, '\n' + preCommitContent);
+            } else {
+                fs.writeFileSync(preCommitHookPath, preCommitContent);
+            }
+        } else {
+            fs.writeFileSync(preCommitHookPath, preCommitContent);
+        }
         try {
             fs.chmodSync(preCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Define the post-commit script path [ds]
+        // Path to post-commit script [ds]
         const postCommitScript = path.join(__dirname, 'post-commit.js').replace(/\\/g, '/');
 
-        // Define the post-commit hook script [ds]
+        // Create post-commit hook script [ds]
         const postCommitHookPath = path.join(hooksDir, 'post-commit');
         const postCommitContent = `#!/bin/sh
 # devsplain native post-commit hook
 echo "Auto-generating comments for files in the last commit..."
 node "${postCommitScript}"${modeArgs} || exit 1
 `;
-        fs.writeFileSync(postCommitHookPath, postCommitContent);
+        // Write post-commit hook safely [ds]
+        if (fs.existsSync(postCommitHookPath)) {
+            const existing = fs.readFileSync(postCommitHookPath, 'utf8');
+            if (!existing.includes('# devsplain native post-commit hook')) {
+                fs.appendFileSync(postCommitHookPath, '\n' + postCommitContent);
+            } else {
+                fs.writeFileSync(postCommitHookPath, postCommitContent);
+            }
+        } else {
+            fs.writeFileSync(postCommitHookPath, postCommitContent);
+        }
         try {
             fs.chmodSync(postCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Inform the user about the successful installation of the post-commit hook [ds]
+        // Log successful installation of post-commit hook [ds]
         console.log(`[devsplain] Git post-commit hook successfully installed at: ${postCommitHookPath}`);
 
-        // Check if a .devsplainignore file exists in the Git root directory [ds]
+        // Path to devsplain ignore file [ds]
         const ignorePath = path.join(gitRoot, '.devsplainignore');
+        const defaultIgnoreLines = [
+            'node_modules/', '.git/', 'dist/', 'build/', 'out/',
+            '.next/', '.nuxt/', '.svelte-kit/',
+            'venv/', 'env/', '.venv/',
+            '.vscode/', '.idea/', 'coverage/',
+            'tests/', '__tests__/', 'fixtures/'
+        ];
+// List of default patterns to ignore [ds]
+
+        const gitignorePath = path.join(gitRoot, '.gitignore');
+        let gitignoreLines = [];
+        if (fs.existsSync(gitignorePath)) {
+            const gitignoreContent = fs.readFileSync(gitignorePath, 'utf8');
+            gitignoreLines = gitignoreContent.split(/\r?\n/)
+                .map(l => l.trim())
+                .filter(l => l && !l.startsWith('#'));
+        }
+
+        // Check if .gitignore file exists [ds]
         if (!fs.existsSync(ignorePath)) {
-            const defaultIgnore = `node_modules/
-.git/
-dist/
-build/
-out/
-.next/
-.nuxt/
-.svelte-kit/
-venv/
-env/
-.venv/
-.vscode/
-.idea/
-coverage/
-tests/
-__tests__/
-fixtures/
-`;
-            fs.writeFileSync(ignorePath, defaultIgnore);
-            console.log(`[devsplain] Created default .devsplainignore file at: ${ignorePath}`);
+            const gitignoreOnly = gitignoreLines.filter(p => !defaultIgnoreLines.includes(p));
+            let content = defaultIgnoreLines.join('\n') + '\n';
+            if (gitignoreOnly.length > 0) {
+                content += '\n# From .gitignore\n' + gitignoreOnly.join('\n') + '\n';
+            }
+            fs.writeFileSync(ignorePath, content);
+            console.log(`[devsplain] Created .devsplainignore at: ${ignorePath}`);
+            if (gitignoreOnly.length > 0) {
+                console.log(`[devsplain] Merged ${gitignoreOnly.length} pattern(s) from .gitignore into .devsplainignore.`);
+            }
+        } else {
+            const existingContent = fs.readFileSync(ignorePath, 'utf8');
+            const existingLines = existingContent.split(/\r?\n/).map(l => l.trim()).filter(l => l && !l.startsWith('#'));
+            const newPatterns = gitignoreLines.filter(p => !existingLines.includes(p));
+            if (newPatterns.length > 0) {
+                const appendContent = '\n# From .gitignore\n' + newPatterns.join('\n') + '\n';
+                fs.appendFileSync(ignorePath, appendContent);
+                console.log(`[devsplain] Merged ${newPatterns.length} new pattern(s) from .gitignore into .devsplainignore.`);
+            } else if (gitignoreLines.length > 0) {
+                console.log('[devsplain] .devsplainignore is already up-to-date with .gitignore patterns.');
+            }
+        // Handle any errors during hook installation [ds]
         }
+
     } catch (e) {
         console.warn('Warning: Could not set up Git hooks (not inside a git repository or git command missing).');
         console.warn(e.message);
     }
 }
 
-// Check if the script is run as the main module [ds]
+// Removes Git hooks installed by devsplain [ds]
+async function removeHooks() {
+    try {
+        const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+        const hooksDir = path.join(gitDir, 'hooks');
+        const hookSignatures = {
+            'pre-commit': '# devsplain native pre-commit hook',
+            'post-commit': '# devsplain native post-commit hook'
+        };
+
+        let removed = 0;
+        // Iterate through hook signatures to remove [ds]
+        for (const [hookName, signature] of Object.entries(hookSignatures)) {
+            const hookPath = path.join(hooksDir, hookName);
+            if (fs.existsSync(hookPath)) {
+                const content = fs.readFileSync(hookPath, 'utf8');
+                if (content.includes(signature)) {
+                    fs.unlinkSync(hookPath);
+                    console.log(`[devsplain] Removed ${hookName} hook at: ${hookPath}`);
+                    removed++;
+                } else {
+                    console.log(`[devsplain] Skipping ${hookName}: not installed by devsplain.`);
+                }
+            } else {
+                console.log(`[devsplain] No ${hookName} hook found at: ${hookPath}`);
+            }
+        }
+
+        // Log removal of hooks [ds]
+        if (removed > 0) {
+            console.log(`[devsplain] Successfully removed ${removed} hook(s).`);
+        } else {
+            console.log('[devsplain] No devsplain hooks were found to remove.');
+        }
+    } catch (e) {
+        console.warn('Warning: Could not remove Git hooks (not inside a git repository or git command missing).');
+        console.warn(e.message);
+    }
+}
+
+// Run installHooks if this script is executed directly [ds]
 if (require.main === module) {
     installHooks();
 }
-// Export the installHooks function for external use [ds]
-module.exports = installHooks;
+// Export installHooks and removeHooks functions [ds]
+module.exports = { installHooks, removeHooks };

package/lib/config.js

@@ -22,8 +22,14 @@ function askSecret(query) {
         process.stdout.write('\n');
         rl.close();
         resolve(key);
+      } else if (char === '\u0008' || char === '\u007f') { // Backspace
+        if (key.length > 0) {
+          key = key.slice(0, -1);
+          process.stdout.write('\b \b');
+        }
       } else if (char === '\u0003') { // Ctrl+C
-        process.exit();
+        process.stdin.setRawMode(false);
+        process.exit(130);
       } else {
         key += char;
         process.stdout.write('*');
@@ -35,7 +41,7 @@ function askSecret(query) {
 
 // Migrates old config to the new format [ds]
 function migrateConfig(oldConfig) {
-  if (oldConfig.provider && !oldConfig.providers) {
+  if (oldConfig && typeof oldConfig === 'object' && oldConfig.provider && !oldConfig.providers) {
     return {
       activeProvider: oldConfig.provider,
       providers: {
@@ -75,7 +81,7 @@ async function getConfig(forceWizard = false) {
     }
   }
 
-  if (!fileConfig || forceWizard) {
+  if (!fileConfig || !fileConfig.activeProvider || !fileConfig.providers || !fileConfig.providers[fileConfig.activeProvider] || forceWizard) {
     let rl = readline.createInterface({
       input: process.stdin,
       output: process.stdout
@@ -274,9 +280,10 @@ async function getConfig(forceWizard = false) {
       ...config.providers[config.activeProvider]
     };
   } else {
+    const active = fileConfig.providers[fileConfig.activeProvider] || {};
     return {
       provider: fileConfig.activeProvider,
-      ...fileConfig.providers[fileConfig.activeProvider]
+      ...active
     };
   }
 }

package/lib/llm.js

@@ -4,13 +4,16 @@ async function fetchWithRetry(url, options, maxRetries = 3, initialDelay = 1000)
     // Loop through each attempt, up to the maximum number of retries [ds]
     for (let attempt = 0; attempt < maxRetries; attempt++) {
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 15000);
+        const timeoutId = setTimeout(() => controller.abort(), 45000);
         try {
             const response = await fetch(url, {
                 ...options,
                 signal: controller.signal
             });
             clearTimeout(timeoutId);
+            if (!response) {
+                throw new Error("No response received from fetch");
+            }
             if (response.ok) {
                 return response;
             }
@@ -22,7 +25,7 @@ async function fetchWithRetry(url, options, maxRetries = 3, initialDelay = 1000)
         } catch (err) {
             clearTimeout(timeoutId);
             if (err.name === 'AbortError') {
-                lastError = new Error("Request timed out after 15 seconds");
+                lastError = new Error("Request timed out after 45 seconds");
             } else {
                 lastError = err;
             }
@@ -46,8 +49,9 @@ async function getComments(code, language, config, mode = 'default') {
     const extMatch = language.match(/\.[0-9a-z]+$/i);
     const ext = extMatch ? extMatch[0].toLowerCase() : '';
     const isPython = ext === '.py';
-    const isRubyOrShell = ['.rb', '.sh', '.php'].includes(ext);
+    const isRubyOrShell = ['.rb', '.sh'].includes(ext);
     const isHTML = ['.html', '.vue', '.svelte'].includes(ext);
+    const isCss = ['.css', '.scss'].includes(ext);
     const isSql = ext === '.sql';
     
     // Define the single-line comment token and examples [ds]
@@ -63,6 +67,10 @@ async function getComments(code, language, config, mode = 'default') {
         singleLineToken = '<!--';
         blockExample = '<!-- Calculates the total price -->';
         inlineExample = '<!-- Check for null values -->';
+    } else if (isCss) {
+        singleLineToken = '/*';
+        blockExample = '/* Calculates the total price */';
+        inlineExample = '/* Check for null values */';
     } else if (isSql) {
         singleLineToken = '--';
         blockExample = '-- Calculates the total price';
@@ -77,6 +85,11 @@ async function getComments(code, language, config, mode = 'default') {
         instruction = `Provide highly detailed block comments above functions, and exhaustive step-by-step inline comments explaining every conditional branch, loop, variable assignment, and logical block inside function bodies. Do not be sparse; explain the code's execution flow in detail.`;
     }
 
+    let rule5 = `5. IMPORTANT: Use ONLY ${singleLineToken} for comments. DO NOT use docstrings or multi-line string literals like """ or ''' for comments.`;
+    if (isCss) {
+        rule5 = `5. IMPORTANT: In CSS/SCSS, you MUST use /* ... */ for comments. DO NOT use // comments under any circumstances.`;
+    }
+
     let prompt = `
 You are a code documentation engine. Analyze the following ${language} code which has line numbers prepended to it.
 ${instruction}
@@ -86,7 +99,7 @@ CRITICAL RULES:
 2. Each object must have exactly two properties: "line" (the integer line number where the comment should be inserted ABOVE) and "comment" (the text of the comment itself).
 3. Do NOT include the original code in your response.
 4. If no comments are needed, return an empty array: [].
-5. IMPORTANT: Use ONLY ${singleLineToken} for comments. DO NOT use docstrings or multi-line string literals like """ or ''' for comments.
+${rule5}
 
 Example Output:
 [
@@ -116,10 +129,15 @@ ${numberedCode}
             });
             data = await response.json();
         } catch (error) {
-            throw new Error("Network Error: Could not connect to the AI provider. Check your internet or API url.");
+            throw new Error(`AI Provider Request Failed: ${error.message}`);
         }
         if (data.error) {
-            throw new Error(`API Error: ${data.error.message}`);
+            const msg = data.error.message || (typeof data.error === 'string' ? data.error : JSON.stringify(data.error));
+            throw new Error(`API Error: ${msg}`);
+        }
+        if (!data.candidates || !data.candidates[0] || !data.candidates[0].content || !data.candidates[0].content.parts || !data.candidates[0].content.parts[0]) {
+            const reason = data.candidates?.[0]?.finishReason || 'Unknown error';
+            throw new Error(`AI Provider returned no content (finish reason: ${reason})`);
         }
         textResponse = data.candidates[0].content.parts[0].text;
     } else if (config.provider === 'claude') {
@@ -145,10 +163,14 @@ ${numberedCode}
             });
             data = await response.json();
         } catch (error) {
-            throw new Error("Network Error: Could not connect to the AI provider. Check your internet or API url.");
+            throw new Error(`AI Provider Request Failed: ${error.message}`);
         }
         if (data.error) {
-            throw new Error(`API Error: ${data.error.message}`);
+            const msg = data.error.message || (typeof data.error === 'string' ? data.error : JSON.stringify(data.error));
+            throw new Error(`API Error: ${msg}`);
+        }
+        if (!data.content || !data.content[0] || typeof data.content[0].text !== 'string') {
+            throw new Error(`AI Provider returned an unexpected response structure: ${JSON.stringify(data)}`);
         }
         textResponse = data.content[0].text;
     } 
@@ -166,6 +188,7 @@ ${numberedCode}
                 },
                 body: JSON.stringify({ 
                     "model": config.model, 
+                    "max_tokens": 8192,
                     "messages": [{ 
                         "role": "user", 
                         "content": prompt 
@@ -174,10 +197,14 @@ ${numberedCode}
             });
             data = await response.json();
         } catch (error) {
-            throw new Error("Network Error: Could not connect to the AI provider. Check your internet or API url.");
+            throw new Error(`AI Provider Request Failed: ${error.message}`);
         }
         if (data.error) {
-            throw new Error(`API Error: ${data.error.message}`);
+            const msg = data.error.message || (typeof data.error === 'string' ? data.error : JSON.stringify(data.error));
+            throw new Error(`API Error: ${msg}`);
+        }
+        if (!data.choices || !data.choices[0] || !data.choices[0].message || typeof data.choices[0].message.content !== 'string') {
+            throw new Error(`AI Provider returned an unexpected response structure: ${JSON.stringify(data)}`);
         }
         textResponse = data.choices[0].message.content;
     }
@@ -220,15 +247,30 @@ ${numberedCode}
             }
 
             const trimmedComment = item.comment.trim();
-            const startsWithCommentMarker = 
-                trimmedComment.startsWith('//') || 
-                trimmedComment.startsWith('/*') || 
-                trimmedComment.startsWith('#') ||
-                trimmedComment.startsWith('<!--') ||
-                trimmedComment.startsWith('--');
-
-            if (!startsWithCommentMarker) {
-                throw new Error(`Security Error: Comment on line ${item.line} does not start with a valid comment character sequence. Rejected: ${trimmedComment}`);
+            const commentLines = trimmedComment.split(/\r?\n/);
+            let inBlock = false;
+            for (const cl of commentLines) {
+                const tcl = cl.trim();
+                if (!tcl) continue;
+                if (inBlock) {
+                    if (tcl.includes('*/') || tcl.includes('-->')) {
+                        inBlock = false;
+                    }
+                    continue;
+                }
+                const startsWithMarker = 
+                    tcl.startsWith('//') || 
+                    tcl.startsWith('/*') || 
+                    tcl.startsWith('*') || 
+                    tcl.startsWith('#') || 
+                    tcl.startsWith('<!--') || 
+                    tcl.startsWith('--');
+                if (!startsWithMarker) {
+                    throw new Error(`Security Error: Comment on line ${item.line} contains invalid non-comment line: "${tcl}"`);
+                }
+                if ((tcl.startsWith('/*') && !tcl.includes('*/')) || (tcl.startsWith('<!--') && !tcl.includes('-->'))) {
+                    inBlock = true;
+                }
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devsplain",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "An agent-agnostic CLI tool that automatically adds JSDoc and inline comments to your code using free LLMs.",
   "author": "mwahaj36",
   "license": "MIT",