commentme 1.0.2 → 1.0.4

package/README.md

@@ -35,6 +35,29 @@ commentme --skim "file-name"
 ### Restore comments to a file
 commentme --unskim "file-name"
 
+### AI Generation
+Generate AI comments and JSDoc-style documentation for your code.
+```bash
+commentme --generate "file-name"
+```
+You can choose to generate comments per function, per class, or per line.
+
+### AI Explanation
+Generate a full markdown explanation of a code file.
+```bash
+commentme --explain "file-name"
+```
+
+### API Key Management
+Set your own OpenRouter API key to use the AI features.
+```bash
+# Set your API key
+commentme --set-key
+
+# Clear your saved API key
+commentme --clear-key
+```
+
 ### Logout
 commentme --logout
 
@@ -43,6 +66,9 @@ commentme --logout
 - Clutter-free and smooth codebase
 - Redact comments from files while keeping references
 - Restore comments back to files whenever required
+- **AI-powered documentation generation (Function/Class/Line level)**
+- **Full code explanation generator (Markdown output)**
+- **Secure API Key management for custom AI models**
 - User authentication and session management 
 - Per-codebase comment organization
 - Dedicated website for more UI friendly & AI edits on comments

package/bin/commentme.js

@@ -8,12 +8,16 @@ import { editComment } from "../editcoms.js";
 import { deleteComment } from "../deletecoms.js";
 import { removeCommentsFromFile as skim } from "../skimcoms.js";
 import { unskimComments as unskim } from "../unskimcoms.js";
+import { generateCommentsPerFunc, generateCommentsPerClass, generateCommentsPerLine, generateExplanation } from "../generate.js";
 // import { connectDB, disconnectDB } from "../config/db.js";
 import { ensureAuth } from "../auth/authGuard.js";
 import { logout } from "../auth/logout.js";
+import { saveApiKey, clearApiKey } from "../utils/apiKeyManager.js";
+import { promptPassword } from "../utils/passwordPrompt.js";
 import dotenv from "dotenv";
 dotenv.config();
 
+
 function promptInput(defaultValue = "") {
   const rl = readline.createInterface({
     input: process.stdin,
@@ -31,6 +35,8 @@ function promptInput(defaultValue = "") {
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
+  console.log("Args:", args);
+  console.log("Command:", command);
 
   try {
     // Show help without connecting to DB or requiring auth
@@ -45,6 +51,10 @@ Commands:
   commentme --delete line-7-7 <file>    Delete a comment
   commentme --skim <file>        Redact comments from a file and store them
   commentme --unskim <file>      Restore comments to a file
+  commentme --generate <file>    Generate AI comments and docs for a file
+  commentme --explain <file>     Generate a full markdown explanation of a code file
+  commentme --set-key            Set your own OpenRouter API key (stored securely)
+  commentme --clear-key          Remove your saved API key
   commentme --logout             Log out from your session
   commentme --help               Show this help message
 `);
@@ -57,7 +67,7 @@ Commands:
 
     // 🔐 Skip auth ONLY for logout
     // 🔐 Skip auth for logout, login, and signup
-    if (command !== "--logout" && command !== "--login" && command !== "--signup") {
+    if (command !== "--logout" && command !== "--login" && command !== "--signup" && command !== "--set-key" && command !== "--clear-key") {
       await ensureAuth();
     }
 
@@ -70,8 +80,6 @@ Commands:
         await import("../auth/signup.js").then(m => m.signup());
         break;
 
-      case "--logout":
-
       case "--get":
         if (args[1] === "lines" && args[2]) {
           await getAllComments(args[2]);
@@ -111,6 +119,55 @@ Commands:
         await unskim(args[1]);
         break;
 
+      case "--generate":
+        if (!args[1]) throw new Error("Usage: commentme --generate <file>");
+        const fileToGenerate = args[1];
+
+        console.log(`
+Select generation type:
+1. Generate comments per function + docs
+2. Generate comments per class + docs
+3. Generate comments per line + docs
+`);
+
+        const choice = await promptInput("1");
+
+        switch (choice.trim()) {
+          case "1":
+            await generateCommentsPerFunc(fileToGenerate);
+            break;
+          case "2":
+            await generateCommentsPerClass(fileToGenerate);
+            break;
+          case "3":
+            await generateCommentsPerLine(fileToGenerate);
+            break;
+          default:
+            console.log("Invalid choice. Defaulting to Per Function.");
+            await generateCommentsPerFunc(fileToGenerate);
+        }
+        break;
+
+      case "--explain":
+        if (!args[1]) throw new Error("Usage: commentme --explain <file>");
+        await generateExplanation(args[1]);
+        break;
+
+      case "--set-key": {
+        console.log("Paste your OpenRouter API key (input is hidden):");
+        const key = await promptPassword("🔑 API Key: ");
+        if (!key || key.trim().length === 0) {
+          console.log("❌ No key provided. Aborted.");
+        } else {
+          saveApiKey(key.trim());
+        }
+        break;
+      }
+
+      case "--clear-key":
+        clearApiKey();
+        break;
+
       case "--logout":
         logout();
         break;
@@ -128,6 +185,10 @@ Commands:
   commentme --delete line-7-7 <file>
   commentme --skim <file>
   commentme --unskim <file>
+  commentme --generate <file>
+  commentme --explain <file>
+  commentme --set-key
+  commentme --clear-key
   commentme --logout
 `);
     }

package/generate.js

@@ -0,0 +1,295 @@
+import fs from "fs";
+import path from "path";
+import { getCurrentUserId } from "./utils/currentUser.js";
+import { getApiKey } from "./utils/apiKeyManager.js";
+
+// ── Model pool for circuit breaker fallback ──
+const FREE_MODELS = [
+    "google/gemma-3-27b-it:free",
+    "meta-llama/llama-3.2-3b-instruct:free",
+    "mistralai/mistral-7b-instruct:free",
+    "google/gemma-3-4b-it:free",
+    "deepseek/deepseek-r1-0528:free",
+];
+
+const MAX_PASSES = 2;           // full cycles through model list
+const COOLDOWN_MS = 5000;       // wait between passes
+
+/**
+ * Resolve the API key: user config > env var > error
+ */
+function resolveApiKey() {
+    // Priority 1: user's own key from ~/.commentme-config.json
+    const userKey = getApiKey();
+    if (userKey) return userKey;
+
+    // Priority 2: env var
+    if (process.env.OPENROUTER_API_KEY) return process.env.OPENROUTER_API_KEY;
+
+    // No key found
+    throw new Error(
+        "No API key found. Set one with:\n" +
+        "  commentme --set-key          (recommended — stores in ~/.commentme-config.json)\n" +
+        "  or set OPENROUTER_API_KEY in your .env file"
+    );
+}
+
+async function callAI(prompt, code) {
+    const apiKey = resolveApiKey();
+
+    for (let pass = 0; pass < MAX_PASSES; pass++) {
+        if (pass > 0) {
+            console.log(`\n⏳ All models rate-limited. Waiting ${COOLDOWN_MS / 1000}s before retry (pass ${pass + 1}/${MAX_PASSES})...`);
+            await new Promise(r => setTimeout(r, COOLDOWN_MS));
+        }
+
+        for (const model of FREE_MODELS) {
+            console.log(`🔄 Trying model: ${model}...`);
+
+            const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({
+                    model,
+                    messages: [
+                        {
+                            role: "user",
+                            content: `${prompt}\n\n---\n\nHere is the code:\n\n${code}`
+                        }
+                    ]
+                })
+            });
+
+            // Auth errors → fail immediately (wrong API key)
+            if (response.status === 401 || response.status === 403) {
+                const errorData = await response.json().catch(() => ({}));
+                throw new Error(`Authentication error (${response.status}): Check your API key. ${JSON.stringify(errorData)}`);
+            }
+
+            // Any other error (429, 404, 400, 503, 521, etc.) → skip to next model
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}));
+                const msg = errorData?.error?.message || `${response.status} ${response.statusText}`;
+                console.warn(`⚠️  ${model} failed (${response.status}: ${msg}), trying next model...`);
+                continue;
+            }
+
+            // Success!
+            const data = await response.json();
+            console.log(`✅ Success with model: ${model}`);
+            return data.choices[0]?.message?.content || "";
+        }
+    }
+
+    throw new Error(
+        "All models are rate-limited after " + MAX_PASSES + " passes. " +
+        "Please wait a few minutes and try again, or set your own API key with: commentme --set-key"
+    );
+}
+
+
+async function processAIResponse(filePath, responseContent) {
+    const parts = responseContent.split("#####DOCS_START#####");
+    let commentedCode = parts[0].trim();
+    const documentation = parts.length > 1 ? parts[1].trim() : "";
+
+    // If the AI returns markdown code blocks, strip them
+    if (commentedCode.startsWith("```") && commentedCode.endsWith("```")) {
+        const lines = commentedCode.split("\n");
+        // Remove first and last lines
+        if (lines.length >= 2) {
+            commentedCode = lines.slice(1, -1).join("\n");
+        }
+    }
+
+    // Write commented code back to file
+    fs.writeFileSync(filePath, commentedCode, "utf8");
+    console.log(`✅ Comments added to ${filePath}`);
+
+    // Write documentation to a new file
+    if (documentation) {
+        const ext = path.extname(filePath);
+        const baseName = path.basename(filePath, ext);
+        const docPath = path.join(path.dirname(filePath), `${baseName}_docs.md`);
+        fs.writeFileSync(docPath, documentation, "utf8");
+        console.log(`✅ Documentation generated at ${docPath}`);
+    }
+}
+
+export async function generateCommentsPerFunc(filePath, codebase = null) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+
+    // Use filename as codebase if not provided
+    if (!codebase) {
+        codebase = path.basename(filePath);
+    }
+
+    // Check authentication (keeping original logic)
+    try {
+        getCurrentUserId();
+    } catch (e) {
+        console.error(e.message);
+        return;
+    }
+
+    const code = fs.readFileSync(filePath, "utf8");
+    console.log(`⏳ Generating function comments for ${filePath}...`);
+
+    const prompt = `
+  You are an expert AI coding assistant. behavior:
+  1. Analyze the provided ${codebase ? codebase : "code"} and take in the reference of the comments if the file already consist comments as understanding the codebase through comments might make you understand the flow as well as the functionality.
+  2. Add meaningful JSDoc-style or block comments above EVERY function definition explaining what it does, its parameters, and return value.
+  3. Keep the original code EXACTLY as is, only adding comments. Do NOT remove existing comments unless they are redundant.
+  4. Generate a comprehensive markdown documentation summarizing each function.
+  5. Output the result in two parts separated by the delimiter "#####DOCS_START#####".
+     Part 1: The full code with added comments.
+     Part 2: The markdown documentation.
+  `;
+
+    try {
+        const response = await callAI(prompt, code);
+        await processAIResponse(filePath, response);
+        console.log(`✨ Successfully generated function comments for ${filePath}`);
+    } catch (error) {
+        console.error("❌ Error generating comments:", error.message);
+    }
+}
+
+export async function generateCommentsPerClass(filePath, codebase = null) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+
+    if (!codebase) {
+        codebase = path.basename(filePath);
+    }
+
+    try {
+        getCurrentUserId();
+    } catch (e) {
+        console.error(e.message);
+        return;
+    }
+
+    const code = fs.readFileSync(filePath, "utf8");
+    console.log(`⏳ Generating class comments for ${filePath}...`);
+
+    const prompt = `
+  You are an expert AI coding assistant. behavior:
+  1. Analyze the provided ${codebase ? codebase : "code"}.
+  2. Add meaningful JSDoc-style or block comments above EVERY class definition explaining its purpose, constructor, and methods.
+  3. Keep the original code EXACTLY as is, only adding comments.
+  4. Generate a comprehensive markdown documentation summarizing each class.
+  5. Output the result in two parts separated by the delimiter "#####DOCS_START#####".
+     Part 1: The full code with added comments.
+     Part 2: The markdown documentation.
+  `;
+
+    try {
+        const response = await callAI(prompt, code);
+        await processAIResponse(filePath, response);
+        console.log(`✨ Successfully generated function comments for ${filePath}`);
+    } catch (error) {
+        console.error("❌ Error generating comments:", error.message);
+    }
+}
+
+export async function generateCommentsPerLine(filePath, codebase = null) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+
+    if (!codebase) {
+        codebase = path.basename(filePath);
+    }
+
+    try {
+        getCurrentUserId();
+    } catch (e) {
+        console.error(e.message);
+        return;
+    }
+
+    const code = fs.readFileSync(filePath, "utf8");
+    console.log(`⏳ Generating line-by-line comments for ${filePath}...`);
+
+    const prompt = `
+  You are an expert AI coding assistant. behavior:
+  1. Analyze the provided ${codebase ? codebase : "code"}.
+  2. Add concise inline comments (// ...) for significant lines of code explaining what they do. Avoid obvious comments.
+  3. Keep the original code logic EXACTLY as is, only adding comments.
+  4. Generate a comprehensive markdown documentation summarizing the flow of the code line-by-line or block-by-block.
+  5. Output the result in two parts separated by the delimiter "#####DOCS_START#####".
+     Part 1: The full code with added comments.
+     Part 2: The markdown documentation.
+  `;
+
+    try {
+        const response = await callAI(prompt, code);
+        await processAIResponse(filePath, response);
+        console.log(`✨ Successfully generated function comments for ${filePath}`);
+    } catch (error) {
+        console.error("❌ Error generating comments:", error.message);
+    }
+}
+
+export async function generateExplanation(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+
+    try {
+        getCurrentUserId();
+    } catch (e) {
+        console.error(e.message);
+        return;
+    }
+
+    const code = fs.readFileSync(filePath, "utf8");
+    const fileName = path.basename(filePath);
+    console.log(`⏳ Generating explanation for ${filePath}...`);
+
+    const prompt = `
+  You are an expert AI coding assistant and technical writer. Your task:
+  1. Read the provided code file "${fileName}" carefully, including ALL existing comments.
+  2. Use the existing comments as references to understand the purpose, flow, and functionality of the code.
+  3. Generate a comprehensive, well-structured Markdown document that explains the ENTIRE file.
+
+  The markdown document MUST include:
+  - **Overview**: A brief summary of what this file does and its role in the project.
+  - **Dependencies / Imports**: List and explain each import and why it's needed.
+  - **Architecture & Flow**: Describe the overall execution flow from top to bottom — how the different parts connect and interact.
+  - **Functions / Classes**: For each function or class, explain:
+    - Purpose
+    - Parameters and return values
+    - Internal logic (step by step)
+    - How it relates to other functions in the file
+  - **Key Logic & Patterns**: Highlight any notable patterns, algorithms, error handling strategies, or design decisions.
+  - **Summary**: A concise wrap-up of the file's responsibilities.
+
+  IMPORTANT:
+  - Output ONLY the markdown documentation, nothing else.
+  - Do NOT include the original code in your output.
+  - Do NOT wrap the output in a code block.
+  - Reference line numbers or function names from the code when explaining.
+  - Make it readable for a developer who has never seen this codebase before.
+  `;
+
+    try {
+        const response = await callAI(prompt, code);
+
+        const ext = path.extname(filePath);
+        const baseName = path.basename(filePath, ext);
+        const docPath = path.join(path.dirname(filePath), `${baseName}_explained.md`);
+
+        fs.writeFileSync(docPath, response.trim(), "utf8");
+        console.log(`✅ Explanation generated at ${docPath}`);
+    } catch (error) {
+        console.error("❌ Error generating explanation:", error.message);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commentme",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A CLI tool to manage, redact and unredact your comments keeping the codebase clutterfree.",
   "type": "module",
   "bin": {

package/utils/apiKeyManager.js

@@ -0,0 +1,51 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const CONFIG_PATH = path.join(os.homedir(), ".commentme-config.json");
+
+export function saveApiKey(key) {
+    const config = loadConfig();
+    config.apiKey = key;
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+
+
+    fs.chmodSync(CONFIG_PATH, 0o600);
+
+    const masked = key.length > 4 ? "****" + key.slice(-4) : "****";
+    console.log(`✅ API key saved (${masked})`);
+    console.log(`   Stored at: ${CONFIG_PATH} (owner-read-only)`);
+}
+
+export function getApiKey() {
+    const config = loadConfig();
+    return config.apiKey || null;
+}
+
+export function clearApiKey() {
+    if (fs.existsSync(CONFIG_PATH)) {
+        const config = loadConfig();
+        delete config.apiKey;
+
+
+        if (Object.keys(config).length === 0) {
+            fs.unlinkSync(CONFIG_PATH);
+        } else {
+            fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+        }
+
+        console.log("✅ API key cleared.");
+    } else {
+        console.log("ℹ️  No saved API key found.");
+    }
+}
+
+
+function loadConfig() {
+    if (!fs.existsSync(CONFIG_PATH)) return {};
+    try {
+        return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+    } catch {
+        return {};
+    }
+}