devsplain 1.8.0 → 2.0.0

package/README.md

@@ -5,6 +5,12 @@ An agent-agnostic CLI tool that adds JSDoc and inline comments using state-of-th
 
 devsplain never rewrites executable code.
 If the original source cannot be reproduced exactly after comment insertion, the operation aborts.
+
+Unlike interactive AI editors, `devsplain` is a single-shot CLI designed for batch documentation passes, CI pipelines, and git hook automation—no agent overhead, no per-file confirmation loops.
+
+> [!TIP]
+> **Built with devsplain**
+> This entire repository is heavily "dogfooded". Every single AI-generated `[ds]` comment you see in the source code of this tool was automatically generated and committed by `devsplain` itself using its native git hooks!
 ---
 
 ## Key Features
@@ -81,10 +87,10 @@ To force re-run the configuration wizard at any time, execute:
 devsplain --config
 ```
 
-Your settings are stored securely in `~/.devsplainrc` (configured with `chmod 600` on POSIX systems to restrict read access).
+Your settings are stored securely in `~/.devsplainrc` (configured with `chmod 600` on POSIX systems to restrict read access, and keystrokes are masked during input).
 
-> [!NOTE]
-> **API Testing Notice:** `devsplain` supports OpenAI, Anthropic, Ollama, Groq, and Gemini endpoints, but the E2E test suite has currently only been aggressively verified against the **Groq** and **Gemini** APIs. If you encounter any unexpected parsing issues or edge-case errors with other providers, please open an issue or submit a PR!
+> [!CAUTION]
+> **Security Note:** Prefer configuring the `DEVSPLAIN_API_KEY` environment variable over using the `--api-key` CLI flag for recurring use. CLI flags may be exposed in your shell history (`~/.bash_history`) and process lists.
 
 ---
 
@@ -133,13 +139,10 @@ devsplain lib/ --prune
 devsplain src/utils.ts --provider gemini --model gemini-2.0-flash --api-key YOUR_KEY
 ```
 
-> [!WARNING]
-> **Directory Traversal Caution**
-> The built-in list of ignored folders (like `node_modules`, `.git`, `dist`, etc.) is not exhaustive. If you run `devsplain` on a broad directory that contains unignored directories (such as local caches or build directories), it may start commenting unwanted files in random folders.
-> 
-> To prevent this, it is highly recommended to either:
-> 1. Use the **Automated Git Hooks** to comment only on files modified in your commits.
-> 2. Pass specific files or selective subfolders manually (e.g., `devsplain src/utils.ts`) instead of targeting broad directories.
+> [!TIP]
+> **Directory Traversal Protection**
+> When you run `devsplain` on a directory, it automatically ignores common build/dependency folders (`node_modules`, `.git`, `dist`, etc.).
+> To ignore custom directories, simply create a `.devsplainignore` file in your project root using the standard `.gitignore` syntax. (A default `.devsplainignore` is automatically generated when you run `--setup-hook`).
 
 ---
 
@@ -168,6 +171,23 @@ Run the hook setup command inside your Git repository:
 devsplain --setup-hook
 ```
 
+### Bypassing the Hook (Manual Override)
+If you ever want to commit code without triggering the AI (for example, if you just ran `devsplain index.js --full` manually and want to freeze those specific comments without the background hook overwriting them), you can bypass the hook entirely:
+```bash
+SKIP_DEVSPLAIN=1 git commit -m "my commit message"
+```
+
+### Forcing or Skipping Auto-Prune
+If you have configured `autoPrune` (aggressive overwrite) in your `~/.devsplainrc` but want to change the behavior for a specific commit:
+- To **force an overwrite** (destroying all human/AI comments before generating new ones) regardless of your config:
+  ```bash
+  DS_OVER=1 git commit -m "overwrite docs"
+  ```
+- To **force preservation** of existing comments (overriding a global prune preference):
+  ```bash
+  DS_KEEP=1 git commit -m "keep docs"
+  ```
+
 ### Pipeline Architecture
 1. **Pre-commit Hook**: Runs your project test suite (`npm test`). If the tests fail, the commit is blocked.
 2. **Post-commit Hook**: 
@@ -179,6 +199,13 @@ devsplain --setup-hook
 
 ---
 
+## Known Limitations & Contributing
+
+> [!NOTE]
+> **API Testing Notice:** `devsplain` natively supports OpenAI, Anthropic, Ollama, Groq, and Gemini endpoints, but the E2E test suite has currently only been aggressively verified against the **Groq** and **Gemini** APIs. If you encounter any unexpected parsing issues or edge-case errors with other providers, please open an issue or submit a PR!
+
+---
+
 ## License
 
 This project is licensed under the MIT License.

package/bin/cli.js

@@ -10,7 +10,7 @@ const { execSync } = require('child_process');
 let rl;
 let askQuestion;
 
-/** Checks if the current Git repository has uncommitted changes [ds] */
+/** Checks if the Git working tree 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 if a given line index is inside a string in a list of code lines [ds] */
+/** Checks if a line is inside a string literal [ds] */
 function isLineInsideString(lines, targetLineIndex, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     let inBacktick = false;
@@ -97,7 +97,7 @@ function isLineInsideString(lines, targetLineIndex, ext = '') {
     return inBacktick || inTripleDouble || inTripleSingle || inSingle || inDouble;
 }
 
-/** Analyzes comments in a list of code lines [ds] */
+/** Analyzes comments in a list of lines [ds] */
 function analyzeComments(lines, ext = '') {
     const isPython = ext.toLowerCase() === '.py';
     const isHTML = ['.html', '.vue', '.svelte'].includes(ext.toLowerCase());
@@ -133,7 +133,6 @@ function analyzeComments(lines, ext = '') {
                 j++;
                 continue;
             }
-            // Check for comment start index in non-Python files [ds]
             if (!inSingle && !inDouble && !inBacktick && !inTripleSingle && !inTripleDouble) {
                 if (isPython) {
                     if (line[j] === '#') {
@@ -199,7 +198,6 @@ function analyzeComments(lines, ext = '') {
                         continue;
                     }
                 }
-            // Check for string literals in non-Python files [ds]
             } else {
                 if (!inSingle && !inDouble) {
                     if (line[j] === '`') {
@@ -239,7 +237,6 @@ function analyzeComments(lines, ext = '') {
                     }
                 }
             }
-            // Increment character index [ds]
             j++;
         }
         if (!isPython) {
@@ -267,7 +264,7 @@ function analyzeComments(lines, ext = '') {
     return analysis;
 }
 
-/** Splices comments into a list of code lines [ds] */
+/** Splices comments into a list of lines [ds] */
 function spliceComments(data, comments, mode = 'default', ext = '') {
     const hasCRLF = data.includes('\r\n');
     const lineEnding = hasCRLF ? '\r\n' : '\n';
@@ -459,7 +456,7 @@ function spliceComments(data, comments, mode = 'default', ext = '') {
     return annotated.map(line => line.text).join(lineEnding);
 }
 
-/** Runs the CLI interface for the commenting tool [ds] */
+/** Runs the CLI application [ds] */
 async function runCLI() {
     rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
@@ -549,6 +546,8 @@ Options:
     if (args.includes('--prune')) mode = 'prune';
     const isDryRun = args.includes('--dry-run');
     const isForce = args.includes('--force');
+    const hasOverwriteFlag = args.includes('--overwrite');
+    const hasKeepFlag = args.includes('--keep');
 
     if (process.env.NODE_ENV !== 'test' && isGitDirty() && !isForce) {
         console.error("Error: Git working tree is dirty. Please commit or stash your changes, or use --force to bypass this check.");
@@ -579,24 +578,48 @@ Options:
     let successCount = 0;
     let failCount = 0;
 
+    const isOverwrite = (hasOverwriteFlag || config.autoPrune) && !hasKeepFlag;
+
+    let userIgnorePatterns = [];
+    try {
+        const ignorePath = path.join(process.cwd(), '.devsplainignore');
+        if (fs.existsSync(ignorePath)) {
+            const ignoreContent = fs.readFileSync(ignorePath, 'utf8');
+            userIgnorePatterns = ignoreContent.split(/\r?\n/)
+                .map(line => line.trim())
+                .filter(line => line && !line.startsWith('#'));
+        }
+    } catch(e) {}
+
+    const defaultIgnoredFolders = [
+        'node_modules', '.git', 'dist', 'build', 'out', 
+        '.next', '.nuxt', '.svelte-kit', 
+        'venv', 'env', '.venv',          
+        '.vscode', '.idea', 'coverage',
+        'tests', '__tests__', 'fixtures'
+    ];
+    const allIgnored = [...defaultIgnoredFolders, ...userIgnorePatterns];
+
+    function isPathIgnored(targetPath) {
+        // Checks if a path is ignored [ds]
+        const filename = path.basename(targetPath);
+        for (const pattern of allIgnored) {
+            const cleanPattern = pattern.replace(/\/$/, '').replace(/\\$/, '');
+            if (filename === cleanPattern) return true;
+            if (pattern.startsWith('*') && filename.endsWith(pattern.slice(1))) return true;
+        }
+        return false;
+    }
+
+    /** Processes a path, scanning directories or analyzing files [ds] */
     async function processPath(targetPath) {
-        // Process a directory or file path [ds]
         const stats = fs.statSync(targetPath);
 
-        if (stats.isDirectory()) {
-            const folderName = path.basename(targetPath);
-            const ignoredFolders = [
-                'node_modules', '.git', 'dist', 'build', 'out', 
-                '.next', '.nuxt', '.svelte-kit', 
-                'venv', 'env', '.venv',          
-                '.vscode', '.idea', 'coverage',
-                'tests', '__tests__', 'fixtures'
-            ];
-
-            if (ignoredFolders.includes(folderName)) {
-                return;
-            }
+        if (isPathIgnored(targetPath)) {
+            return;
+        }
 
+        if (stats.isDirectory()) {
             console.log(`\n Scanning directory: ${targetPath}`);
             const items = fs.readdirSync(targetPath);
             for (const item of items) {
@@ -628,7 +651,8 @@ Options:
                 let comments = [];
                 let commentedCode;
                 if (mode !== 'clean' && mode !== 'prune') {
-                    const cleanData = spliceComments(data, [], 'clean', ext);
+                    const preProcessMode = isOverwrite ? 'prune' : 'clean';
+                    const cleanData = spliceComments(data, [], preProcessMode, ext);
                     comments = await getComments(cleanData, filename, config, mode);
                     commentedCode = spliceComments(cleanData, comments, mode, ext);
                 } else {
@@ -677,7 +701,6 @@ Options:
     rl.close();
 }
 
-// Run the CLI interface if this script is the main module [ds]
 if (require.main === module) {
     runCLI().catch(err => {
         console.error(err);

package/bin/post-commit.js

@@ -3,60 +3,61 @@ const fs = require('fs');
 const path = require('path');
 const { spliceComments } = require('./cli');
 
-/** Main execution block [ds] */
+/** Main execution block for post-commit hook [ds] */
 try {
-    // Allow users to completely bypass the AI hook using an environment variable [ds]
+    // Check if SKIP_DEVSPLAIN environment variable is set [ds]
     if (process.env.SKIP_DEVSPLAIN) {
         console.log('[devsplain] SKIP_DEVSPLAIN is set. Bypassing AI generation.');
         process.exit(0);
     }
 
-    // Prevent the hook from firing during rebases, merges, or cherry-picks [ds]
+    // Determine if Git is in a rebasing, merging, or cherry-picking state [ds]
     const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
     const isRebasing = fs.existsSync(path.join(gitDir, 'rebase-merge')) || fs.existsSync(path.join(gitDir, 'rebase-apply'));
     const isMerging = fs.existsSync(path.join(gitDir, 'MERGE_HEAD'));
     const isCherryPicking = fs.existsSync(path.join(gitDir, 'CHERRY_PICK_HEAD'));
 
+    // Exit if Git is in a rebasing, merging, or cherry-picking state to avoid history conflicts [ds]
     if (isRebasing || isMerging || isCherryPicking) {
         console.log('[devsplain] Skipping AI comment generation during git rebase/merge/cherry-pick to avoid history conflicts.');
         process.exit(0);
     }
 
-    /** Check if the current operation is a rebase, merge or cherry-pick [ds] */
+    // Retrieve the last commit message [ds]
     const lastCommitMsg = execSync('git log -1 --format=%s', { encoding: 'utf8' }).trim();
     if (lastCommitMsg === 'docs: auto-generated comments by devsplain') {
         process.exit(0);
     }
 
-    // Get the last commit message [ds]
+    // 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();
     if (!changedFilesStr) {
         process.exit(0);
     }
     const changedFiles = changedFilesStr.split(/\r?\n/);
 
-    /** List of valid file extensions for commenting [ds] */
+    /** List of valid file extensions for auto-commenting [ds] */
     const validExtensions = [
         '.js', '.jsx', '.ts', '.tsx', '.html', '.css', '.scss', '.vue', '.svelte',
         '.py', '.java', '.c', '.cpp', '.cs', '.go', '.rb', '.php', '.rs',
         '.swift', '.kt', '.dart', '.sh'
     ];
 
-    /** Filter files to be commented [ds] */
+    /** Filter function to determine which files to auto-comment [ds] */
     const filesToComment = changedFiles.filter(file => {
         const ext = path.extname(file).toLowerCase();
         const isIgnored = file.includes('node_modules/') || file.includes('tests/') || file.includes('__tests__/') || file.includes('fixtures/');
         return validExtensions.includes(ext) && fs.existsSync(file) && !isIgnored;
     });
 
-    // Check if there are any files to comment [ds]
     if (filesToComment.length === 0) {
         process.exit(0);
     }
 
+    // Log the number of files found for auto-commenting [ds]
     console.log(`[devsplain] Found ${filesToComment.length} file(s) in the last commit to auto-comment.`);
 
-    // Parse command line arguments for mode flag [ds]
+    // Parse command-line arguments for mode flags [ds]
     const args = process.argv.slice(2);
     let modeFlag = '';
     if (args.includes('--light')) modeFlag = ' --light';
@@ -65,8 +66,9 @@ try {
     let commentedAny = false;
     const successfullyCommentedFiles = [];
 
-    /** Iterate over files to comment [ds] */
+    /** Loop through each file to auto-comment [ds] */
     for (const file of filesToComment) {
+        // Attempt to read file contents and previous version [ds]
         try {
             const ext = path.extname(file).toLowerCase();
             const contentHead = fs.readFileSync(file, 'utf8');
@@ -79,11 +81,12 @@ try {
             } catch (prevErr) {
             }
 
-            // Compare file content before and after the last commit [ds]
+            // Check if file contents have changed (ignoring comments) [ds]
             if (contentPrev) {
                 const cleanHead = spliceComments(contentHead, [], 'prune', ext);
                 const cleanPrev = spliceComments(contentPrev, [], 'prune', ext);
-                if (cleanHead === cleanPrev) {
+                const isExplicitOverwrite = !!process.env.DS_OVER;
+                if (cleanHead === cleanPrev && !isExplicitOverwrite) {
                     console.log(`[devsplain] Skipping ${file}: commit contains only comment changes.`);
                     continue;
                 }
@@ -91,11 +94,16 @@ try {
         } catch (cleanErr) {
         }
 
-        // Comment the file using the CLI [ds]
+        // 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}`, { stdio: 'inherit' });
+            execSync(`node "${cliPath}" "${file}" --force${modeFlag}${extraFlags}`, { stdio: 'inherit' });
             commentedAny = true;
             successfullyCommentedFiles.push(file);
         } catch (err) {
@@ -103,16 +111,14 @@ try {
         }
     }
 
-    /** Stage and commit auto-generated comments if any [ds] */
+    /** If any files were successfully commented, stage and commit changes [ds] */
     if (commentedAny) {
-        // Only stage the exact files that the AI touched to avoid accidentally committing unstaged work [ds]
         for (const file of successfullyCommentedFiles) {
             try {
                 execSync(`git add "${file}"`);
             } catch (addErr) {}
         }
         
-        // Check if there are actually staged changes now [ds]
         const stagedChanges = execSync('git diff --cached --name-only', { encoding: 'utf8' }).trim();
         if (stagedChanges.length > 0) {
             console.log('[devsplain] Staging and committing auto-generated comments...');
@@ -120,7 +126,7 @@ try {
             console.log('[devsplain] Comments committed successfully! Rollback via: git reset --hard HEAD~1');
         }
     }
-/** Catch and log any errors [ds] */
+// Catch and log any errors that occur during execution [ds]
 } catch (e) {
     console.warn(`[devsplain] Warning: post-commit hook script failed: ${e.message}`);
 }

package/bin/setup-hook.js

@@ -3,26 +3,26 @@ const path = require('path');
 const { execSync } = require('child_process');
 const readline = require('readline');
 
-/** Installs Git hooks for the repository. [ds] */
+/** Installs Git hooks for auto-generating comments [ds] */
 async function installHooks() {
     try {
         const gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+        const gitRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
         const hooksDir = path.join(gitDir, 'hooks');
         if (!fs.existsSync(hooksDir)) {
             fs.mkdirSync(hooksDir, { recursive: true });
         }
 
+        // Default commenting mode for Git commits [ds]
         let modeChoice = '1';
-        // Check if process is running in a TTY to prompt for user input [ds]
+        // Check if running in a TTY to prompt user for commenting mode [ds]
         if (process.stdout.isTTY) {
             const rl = readline.createInterface({
                 input: process.stdin,
                 output: process.stdout
             });
-            // Create a readline interface for user input [ds]
             const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
-            // Display a menu for the user to select the default commenting mode [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)');
@@ -32,7 +32,6 @@ async function installHooks() {
             rl.close();
         }
 
-        // Determine the command line arguments based on the chosen mode [ds]
         let modeArgs = '';
         if (modeChoice === '2') {
             modeArgs = ' --light';
@@ -40,7 +39,7 @@ async function installHooks() {
             modeArgs = ' --full';
         }
 
-        // Define the path to the pre-commit hook file [ds]
+        // Path to pre-commit hook script [ds]
         const preCommitHookPath = path.join(hooksDir, 'pre-commit');
         const preCommitContent = `#!/bin/sh
 # devsplain native pre-commit hook
@@ -49,16 +48,16 @@ if [ -f package.json ] && grep -q '"test"' package.json 2>/dev/null; then
   npm test || exit 1
 fi
 `;
+        // Write pre-commit hook content to file [ds]
         fs.writeFileSync(preCommitHookPath, preCommitContent);
-        // Attempt to set the execute permissions for the pre-commit hook file [ds]
         try {
             fs.chmodSync(preCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Define the path to the post-commit script [ds]
+        // Path to post-commit script [ds]
         const postCommitScript = path.join(__dirname, 'post-commit.js').replace(/\\/g, '/');
 
-        // Define the path to the post-commit hook file [ds]
+        // Path to post-commit hook script [ds]
         const postCommitHookPath = path.join(hooksDir, 'post-commit');
         const postCommitContent = `#!/bin/sh
 # devsplain native post-commit hook
@@ -66,22 +65,46 @@ echo "Auto-generating comments for files in the last commit..."
 node "${postCommitScript}"${modeArgs} || exit 1
 `;
         fs.writeFileSync(postCommitHookPath, postCommitContent);
-        // Attempt to set the execute permissions for the post-commit hook file [ds]
         try {
             fs.chmodSync(postCommitHookPath, 0o755);
         } catch (err) {}
 
-        // Display a success message if the hooks are installed successfully [ds]
-        console.log('Success: Native Git pre-commit and post-commit hooks installed successfully!');
-    // Catch and handle any exceptions that occur during the installation process [ds]
+        console.log(`[devsplain] Git post-commit hook successfully installed at: ${postCommitHookPath}`);
+
+        // Log successful installation of post-commit hook [ds]
+        const ignorePath = path.join(gitRoot, '.devsplainignore');
+        // Check if .devsplainignore 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}`);
+        }
     } 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 this script is being run directly (not being required as a module) [ds]
+// Run installHooks if this script is the main module [ds]
 if (require.main === module) {
     installHooks();
 }
-// Export the installHooks function as a module [ds]
+// Export installHooks function [ds]
 module.exports = installHooks;

package/lib/config.js

@@ -4,7 +4,37 @@ const os = require('os');
 const readline = require('readline');
 const configPath = path.join(os.homedir(), '.devsplainrc');
 
-/** Retrieves the configuration for the AI provider. If a configuration file exists and no forceWizard flag is provided, the existing configuration will be returned. Otherwise, the function will prompt the user to input their configuration details. [ds] */
+/** Asks the user for a secret input, such as an API key, without echoing the input to the console. [ds] */
+function askSecret(query) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    process.stdout.write(query);
+    process.stdin.setRawMode(true);
+    let key = '';
+    // Handle key presses, including enter, backspace, and Ctrl+C [ds]
+    const onData = (char) => {
+      char = char.toString();
+      if (char === '\n' || char === '\r') {
+        process.stdin.setRawMode(false);
+        process.stdin.removeListener('data', onData);
+        process.stdout.write('\n');
+        rl.close();
+        resolve(key);
+      } else if (char === '\u0003') { // Ctrl+C
+        process.exit();
+      } else {
+        key += char;
+        process.stdout.write('*');
+      }
+    };
+    process.stdin.on('data', onData);
+  });
+}
+
+/** Retrieves the configuration, either from environment variables or by prompting the user to set up a configuration file. [ds] */
 async function getConfig(forceWizard = false) {
   if (process.env.DEVSPLAIN_API_KEY || process.env.DEVSPLAIN_PROVIDER) {
     const provider = process.env.DEVSPLAIN_PROVIDER || 'gemini';
@@ -18,24 +48,23 @@ async function getConfig(forceWizard = false) {
     };
   }
 
-  // Check if configuration file exists or if forceWizard flag is set [ds]
+  // If no configuration file exists or the forceWizard flag is set, prompt the user to set up a configuration [ds]
   if (!fs.existsSync(configPath) || forceWizard) {
-    const rl = readline.createInterface({
+    let rl = readline.createInterface({
       input: process.stdin,
       output: process.stdout
     });
-    const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+    let askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
 
     let config = null;
     let confirmed = false;
 
-    // Continuously prompt user for configuration details until confirmation [ds]
     while (!confirmed) {
       let baseUrl = "";
       let model = "";
       let provider = "";
 
-      // Display available AI provider options [ds]
+      // Display a menu of available AI providers [ds]
       console.log("\nWhich AI Provider Do You want to use?");
       console.log("1. Groq (Free, Fast, Llama-3)");
       console.log("2. Gemini (Free Tier)");
@@ -43,10 +72,8 @@ async function getConfig(forceWizard = false) {
       console.log("4. Custom (Ollama, local, etc)");
       console.log("5. Claude (Anthropic)");
 
-      // Get user's selected AI provider option [ds]
       const choice = await askQuestion("Select (1-5): ");
 
-      // Handle selected AI provider option [ds]
       if (choice === '1') {
         provider = 'groq';
         baseUrl = 'https://api.groq.com/openai';
@@ -80,25 +107,43 @@ async function getConfig(forceWizard = false) {
         continue;
       }
 
-      // Get API key from user [ds]
-      const apiKey = await askQuestion("Paste your API key (leave blank for local models): ");
+      let apiKey = '';
+      // If running in a TTY, use a secure method to prompt for the API key [ds]
+      if (process.stdin.isTTY) {
+        rl.close();
+        apiKey = await askSecret("Paste your API key (leave blank for local models): ");
+
+        rl = readline.createInterface({
+          input: process.stdin,
+          output: process.stdout
+        });
+        askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+      } else {
+        apiKey = await askQuestion("Paste your API key (leave blank for local models): ");
+      }
+
+      // Ask the user if they want to prune existing comments [ds]
+      const pruneAns = await askQuestion("Do you want devsplain to aggressively prune (overwrite) existing human/AI comments? (y/n, default: n): ");
+      const autoPrune = pruneAns.toLowerCase() === 'y';
 
-      // Display configuration summary [ds]
+      // Display a summary of the configuration [ds]
       console.log("\n--- Configuration Summary ---");
-      console.log(`Provider: ${provider}`);
-      console.log(`Model:    ${model}`);
-      console.log(`Base URL: ${baseUrl || 'N/A'}`);
-      console.log(`API Key:  ${apiKey ? apiKey.substring(0, 4) + '*'.repeat(Math.max(0, apiKey.length - 4)) : 'None'}`);
+      console.log(`Provider:     ${provider}`);
+      console.log(`Model:        ${model}`);
+      console.log(`Base URL:     ${baseUrl || 'N/A'}`);
+      console.log(`API Key:      ${apiKey ? apiKey.substring(0, 4) + '*'.repeat(Math.max(0, apiKey.length - 4)) : 'None'}`);
+      console.log(`Auto-Prune:   ${autoPrune ? 'Yes' : 'No'}`);
       console.log("-----------------------------\n");
 
-      // Confirm configuration with user [ds]
+      // Confirm the configuration with the user [ds]
       const confirm = await askQuestion("Does this look correct? (y/n, default: y): ");
       if (confirm.toLowerCase() === 'y' || confirm.trim() === '') {
         config = {
           provider,
           apiKey,
           model,
-          baseUrl
+          baseUrl,
+          autoPrune
         };
         confirmed = true;
       } else {
@@ -108,10 +153,10 @@ async function getConfig(forceWizard = false) {
 
     rl.close();
 
-    // Write configuration to file [ds]
+    // Write the configuration to a file [ds]
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
     try {
-      // Set file permissions to prevent unauthorized access [ds]
+      // Set permissions on the configuration file to prevent other users from reading it [ds]
       if (process.platform !== 'win32') {
         fs.chmodSync(configPath, 0o600);
       }
@@ -120,11 +165,9 @@ async function getConfig(forceWizard = false) {
 
     return config;
   } else {
-    // Read existing configuration from file [ds]
     const rawData = fs.readFileSync(configPath, 'utf8');
     return JSON.parse(rawData);
   }
 }
 
-// Export the getConfig function [ds]
 module.exports = { getConfig };

package/package.json

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