neuro-commit 0.1.2 → 0.2.0

package/README.md

@@ -8,11 +8,12 @@
   <a href="https://github.com/cr1ma/neuro-commit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/cr1ma/neuro-commit" alt="license"></a>
   <a href="https://github.com/cr1ma/neuro-commit/actions/workflows/publish.yml"><img src="https://github.com/cr1ma/neuro-commit/actions/workflows/publish.yml/badge.svg" alt="publish status"></a>
   <a href="https://github.com/cr1ma/neuro-commit/issues"><img src="https://img.shields.io/github/issues/cr1ma/neuro-commit" alt="open issues"></a>
+  <a href="https://github.com/cr1ma/neuro-commit"><img src="https://img.shields.io/github/stars/cr1ma/neuro-commit" alt="stars"></a>
 </p>
 
 ---
 
-**NeuroCommit** is a zero-config CLI tool that analyzes your staged Git changes and generates a clean, structured Markdown summary — ready to be fed into any AI/LLM for high-quality commit message generation.
+**NeuroCommit** is a CLI tool that analyzes your staged Git changes and generates commit messages — either automatically via OpenAI API or as a structured prompt you can paste into any LLM.
 
 <p align="center">
   <img src="docs/assets/neuro-commit-screenshot.png" alt="NeuroCommit CLI screenshot" width="700">
@@ -23,6 +24,7 @@
 - [Features](#-features)
 - [Quick Start](#-quick-start)
 - [How It Works](#-how-it-works)
+- [Configuration](#-configuration)
 - [Development](#-development)
 - [Contributing](#-contributing)
 - [Security](#-security)
@@ -31,12 +33,14 @@
 
 ## ✨ Features
 
-- **Zero configuration** — works out of the box with any Git repository
-- **Interactive TUI** — beautiful terminal menu with keyboard navigation
-- **Smart lock file handling** — detects lock files (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock`, etc.) and omits their noisy diffs
-- **Token estimation** — reports estimated token count (using `o200k_base` tokenizer) so you know the prompt size before pasting into an LLM
-- **Structured Markdown output** — generates a `neuro-commit.md` with file list, per-file stats, and full diff
-- **Update notifications** — automatically notifies you when a new version is available
+- **AI Commit mode** — generates and commits messages automatically using OpenAI API (`gpt-5-nano`) with Structured Outputs
+- **Manual mode** — saves a prompt to `neuro-commit.md` for pasting into any LLM (ChatGPT, Claude, etc.)
+- **Conventional Commits** — always uses `feat:`, `fix:`, `docs:`, `refactor:`, etc.
+- **Smart lock file handling** — detects lock files and omits their noisy diffs
+- **Minimal UI** — clean terminal interface, no visual clutter
+- **Multi-language** — commit message body in English, Ukrainian, Russian, German, French, or Spanish
+- **Configurable** — auto-commit, auto-push, commit history context, dev mode
+- **Secure** — API key via environment variable only, no shell injection vectors
 
 ## 🚀 Quick Start
 
@@ -58,20 +62,52 @@ Then run:
 neuro-commit
 ```
 
+### Setting up OpenAI API Key
+
+For AI Commit mode, set your API key:
+
+```bash
+# Linux / macOS
+export OPENAI_API_KEY="sk-..."
+
+# Windows PowerShell
+$env:OPENAI_API_KEY = "sk-..."
+
+# Windows CMD
+set OPENAI_API_KEY=sk-...
+```
+
 ## 📖 How It Works
 
+### AI Commit Mode
+
 1. Stage your changes with `git add`
-2. Run `neuro-commit`
-3. Select **Commit** mode from the interactive menu
-4. The tool collects your staged diff, file list, and per-file stats
-5. A `neuro-commit.md` file is generated in the current directory containing:
-   - File list with statuses (`Added`, `Modified`, `Deleted`, etc.) and per-file insertions/deletions
-   - Lock file entries listed without their diffs
-   - Summary line with total files changed, insertions, and deletions
-   - Full diff output in a fenced `diff` code block
-6. Copy the contents of `neuro-commit.md` into your preferred AI assistant and ask it to write a commit message
-
-> **Tip:** Lock files (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `uv.lock`, `Cargo.lock`, and others) are listed as changed but their diffs are omitted to keep the output clean and token-efficient.
+2. Run `neuro-commit` → select **AI Commit**
+3. Review the file summary and confirm generation
+4. The tool sends your diff to OpenAI API and generates a commit message
+5. Choose: **Commit**, **Edit**, **Regenerate**, or **Cancel**
+
+### Manual Mode
+
+1. Stage your changes with `git add`
+2. Run `neuro-commit` → select **Manual Mode**
+3. A `neuro-commit.md` file is generated with the full prompt
+4. Paste into your preferred LLM and get a commit message
+
+> Both modes use the same prompt — the only difference is delivery method.
+
+## ⚙️ Configuration
+
+Settings are stored in `~/.neurocommit/config.json`. Access via the **Settings** menu.
+
+| Setting        | Default | Description                            |
+| -------------- | ------- | -------------------------------------- |
+| Language       | `en`    | Commit message body language           |
+| Max length     | `72`    | Title character limit                  |
+| Auto-commit    | `OFF`   | Commit immediately after generation    |
+| Auto-push      | `OFF`   | Push after committing                  |
+| Commit history | `5`     | Recent commits included as AI context  |
+| Dev mode       | `OFF`   | Store API responses (OpenAI dashboard) |
 
 ## 🔧 Development
 

package/bin/neuro-commit.js

@@ -1,145 +1,99 @@
 #!/usr/bin/env node
 
-const readline = require("readline");
 const { runCommitMode } = require("../src/commit");
-
-const banner = `
-███╗   ██╗███████╗██╗   ██╗██████╗  ██████╗        ██████╗ ██████╗ ███╗   ███╗███╗   ███╗██╗████████╗
-████╗  ██║██╔════╝██║   ██║██╔══██╗██╔═══██╗      ██╔════╝██╔═══██╗████╗ ████║████╗ ████║██║╚══██╔══╝
-██╔██╗ ██║█████╗  ██║   ██║██████╔╝██║   ██║█████╗██║     ██║   ██║██╔████╔██║██╔████╔██║██║   ██║   
-██║╚██╗██║██╔══╝  ██║   ██║██╔══██╗██║   ██║╚════╝██║     ██║   ██║██║╚██╔╝██║██║╚██╔╝██║██║   ██║   
-██║ ╚████║███████╗╚██████╔╝██║  ██║╚██████╔╝      ╚██████╗╚██████╔╝██║ ╚═╝ ██║██║ ╚═╝ ██║██║   ██║   
-╚═╝  ╚═══╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝ ╚═════╝        ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝     ╚═╝╚═╝   ╚═╝                                                                                                      
-`;
-
-// --- Menu options ---
-const menuItems = [
-  { label: "Commit", icon: "📝", description: "Generate a commit message" },
-];
-
-// --- ANSI helpers ---
-const RESET = "\x1b[0m";
-const BOLD = "\x1b[1m";
-const DIM = "\x1b[2m";
-const GREEN = "\x1b[32m";
-const CYAN = "\x1b[36m";
-const HIDE_CURSOR = "\x1b[?25l";
-const SHOW_CURSOR = "\x1b[?25h";
-
-// Ensure cursor is restored if the process exits unexpectedly
-process.on("exit", () => {
-  process.stdout.write(SHOW_CURSOR);
-});
-
-process.on("SIGINT", () => {
+const { runAiCommitMode } = require("../src/aiCommit");
+const { runSettingsMenu } = require("../src/settings");
+const { isAiAvailable } = require("../src/config");
+const {
+  RESET,
+  BOLD,
+  DIM,
+  RED,
+  CYAN,
+  SHOW_CURSOR,
+  showSelectMenu,
+} = require("../src/ui");
+const pkg = require("../package.json");
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`\n${BOLD}neuro-commit${RESET} v${pkg.version}\n`);
+  console.log(`Usage:  neuro-commit`);
+  console.log(`Flags:  -h, --help  |  -v, --version\n`);
   process.exit(0);
-});
+}
 
-function renderMenu(selectedIndex) {
-  const lines = menuItems.length + 2;
-  process.stdout.write(`\x1b[${lines}A`);
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(`v${pkg.version}`);
+  process.exit(0);
+}
 
-  process.stdout.write(
-    `${CYAN}?${RESET} ${BOLD}Select mode:${RESET} ${DIM}(use arrow keys)${RESET}\n\n`,
-  );
+process.on("exit", () => process.stdout.write(SHOW_CURSOR));
+process.on("SIGINT", () => process.exit(0));
 
-  for (let i = 0; i < menuItems.length; i++) {
-    const { label, icon, description } = menuItems[i];
-    if (i === selectedIndex) {
-      process.stdout.write(
-        `  ${GREEN}❯ ${icon}  ${BOLD}${label}${RESET}  ${DIM}— ${description}${RESET}\n`,
-      );
-    } else {
-      process.stdout.write(
-        `    ${icon}  ${label}  ${DIM}— ${description}${RESET}\n`,
+/**
+ * Non-blocking version check — runs once, prints hint if outdated.
+ */
+async function checkForUpdate() {
+  try {
+    const { default: latestVersion } = await import("latest-version");
+    const latest = await latestVersion(pkg.name);
+    if (latest && latest !== pkg.version) {
+      console.log(
+        `${DIM}Update available: ${pkg.version} → ${CYAN}${latest}${RESET}${DIM}  (npm i -g ${pkg.name})${RESET}`,
       );
     }
+  } catch {
+    // silently ignore network errors
   }
 }
 
-function showMenu() {
-  return new Promise((resolve) => {
-    let selected = 0;
-
-    if (!process.stdin.isTTY) {
-      console.error("Error: interactive mode requires a TTY terminal.");
-      process.exit(1);
-    }
-
-    process.stdout.write(HIDE_CURSOR);
-
-    process.stdout.write("\n".repeat(menuItems.length + 2));
-    renderMenu(selected);
-
-    readline.emitKeypressEvents(process.stdin);
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-
-    function onKeyPress(str, key) {
-      if (!key) return;
-
-      if ((key.ctrl && key.name === "c") || key.name === "q") {
-        cleanup();
-        console.log("\n👋 Goodbye!");
-        process.exit(0);
-      }
-
-      if (key.name === "up" || key.name === "k") {
-        selected = (selected - 1 + menuItems.length) % menuItems.length;
-        renderMenu(selected);
+async function main() {
+  while (true) {
+    console.clear();
+    console.log(
+      `\n${BOLD}neuro-commit${RESET} ${DIM}v${pkg.version}${RESET}\n`,
+    );
+
+    // fire-and-forget update check (only first iteration matters visually)
+    checkForUpdate();
+
+    const choice = await showSelectMenu("Mode:", [
+      { label: "AI Commit", description: "generate & commit" },
+      { label: "Manual Mode", description: "save prompt to .md" },
+      { label: "Settings" },
+    ]);
+
+    switch (choice) {
+      case 0: {
+        if (!isAiAvailable()) {
+          console.log(
+            `\n${RED}✖${RESET} Set ${CYAN}OPENAI_API_KEY${RESET} env variable first.`,
+          );
+          console.log(
+            `${DIM}PowerShell:  $env:OPENAI_API_KEY = "sk-..."${RESET}`,
+          );
+          console.log(
+            `${DIM}Linux/macOS: export OPENAI_API_KEY="sk-..."${RESET}\n`,
+          );
+          await new Promise((r) => setTimeout(r, 2000));
+          break;
+        }
+        console.clear();
+        await runAiCommitMode();
         return;
       }
-
-      if (key.name === "down" || key.name === "j") {
-        selected = (selected + 1) % menuItems.length;
-        renderMenu(selected);
+      case 1:
+        console.clear();
+        runCommitMode();
         return;
-      }
-
-      if (key.name === "return") {
-        cleanup();
-        resolve(selected);
+      case 2:
+        await runSettingsMenu();
+        break;
+      default:
         return;
-      }
-    }
-
-    function cleanup() {
-      process.stdin.removeListener("keypress", onKeyPress);
-      process.stdin.setRawMode(false);
-      process.stdin.pause();
-      process.stdout.write(SHOW_CURSOR);
     }
-
-    process.stdin.on("keypress", onKeyPress);
-  });
-}
-
-// --- Entry point ---
-async function main() {
-  console.clear();
-  console.log(banner);
-
-  try {
-    const { default: updateNotifier } = await import("update-notifier");
-    const pkg = require("../package.json");
-
-    updateNotifier({
-      pkg,
-      updateCheckInterval: 1000 * 60 * 60 * 24,
-    }).notify({
-      defer: false,
-      isGlobal: true,
-    });
-  } catch {
-    // Ignore update check errors
-  }
-
-  const choice = await showMenu();
-
-  switch (choice) {
-    case 0:
-      runCommitMode();
-      break;
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neuro-commit",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "neuro-commit CLI utility",
   "author": "cr1ma.dev",
   "bin": {
@@ -38,7 +38,9 @@
     "globals": "^17.3.0"
   },
   "dependencies": {
+    "latest-version": "^9.0.0",
+    "openai": "^6.22.0",
     "tiktoken": "^1.0.22",
-    "update-notifier": "^7.3.1"
+    "zod": "^4.3.6"
   }
 }

package/src/ai.js

@@ -0,0 +1,234 @@
+const OpenAI = require("openai");
+const { z } = require("zod");
+const { zodTextFormat } = require("openai/helpers/zod");
+const { get_encoding } = require("tiktoken");
+const { getApiKey, loadConfig } = require("./config");
+const { isLockFile, statusLabel } = require("./git");
+
+// Lazy-initialized tiktoken encoder (o200k_base for GPT-5 / GPT-4o family)
+let _encoder = null;
+
+/**
+ * Count tokens accurately using tiktoken (o200k_base).
+ */
+function countTokens(text) {
+  if (!_encoder) _encoder = get_encoding("o200k_base");
+  return _encoder.encode(text).length;
+}
+
+// Pricing per 1M tokens — gpt-5-nano
+const MODEL_PRICING = {
+  input: 0.05,
+  cachedInput: 0.005,
+  output: 0.4,
+};
+
+// Structured output schema
+const CommitMessage = z.object({
+  title: z
+    .string()
+    .describe("Commit title line (max ~72 chars, imperative mood, no period)"),
+  body: z
+    .array(z.string())
+    .describe("Bullet points describing key changes (without leading dash)"),
+});
+
+/**
+ * Build a file summary string for the prompt.
+ */
+function buildFilesInfo(stagedFiles, numstat) {
+  const statMap = new Map();
+  for (const entry of numstat) {
+    statMap.set(entry.file, entry);
+  }
+
+  const lines = [];
+  for (const { status, file } of stagedFiles) {
+    const label = statusLabel(status).padEnd(10);
+    const s = statMap.get(file);
+    if (isLockFile(file)) {
+      lines.push(`  ${label} ${file} | lock file (diff omitted)`);
+    } else {
+      const stat = s ? `| +${s.added} -${s.deleted}` : "";
+      lines.push(`  ${label} ${file} ${stat}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Build system prompt. Always uses Conventional Commits.
+ */
+function buildSystemPrompt(config, context = {}) {
+  const { language, maxLength } = config;
+
+  let langInstruction = "";
+  if (language && language !== "en") {
+    langInstruction = `\nWrite the commit message body in ${language} language. Keep the type prefix in English.`;
+  }
+
+  let branchContext = "";
+  if (context.branch) {
+    branchContext = `\nCurrent branch: ${context.branch}`;
+  }
+
+  let historyContext = "";
+  if (context.recentCommits && context.recentCommits.length > 0) {
+    historyContext = `\nRecent commits for style reference:\n${context.recentCommits.map((c) => `  - ${c}`).join("\n")}`;
+  }
+
+  return `You are an expert at writing clear, concise git commit messages.
+
+Rules:
+1. Use Conventional Commits: feat:, fix:, docs:, style:, refactor:, test:, chore:, perf:, ci:, build:
+2. If changes affect a specific scope, use parentheses: feat(auth): ...
+3. Title max ${maxLength} chars, imperative mood, no period at end.
+4. Body: concise bullet points for key changes.
+5. Be specific — WHAT changed and WHY.
+6. Omit file paths unless essential. Omit lock file changes.
+${langInstruction}
+${branchContext}
+${historyContext}`.trim();
+}
+
+/**
+ * Build user prompt with the diff content.
+ */
+function buildUserPrompt(filesInfo, diff) {
+  return `Staged changes:
+
+Files:
+${filesInfo}
+
+Diff:
+\`\`\`diff
+${diff}
+\`\`\`
+
+Generate a commit message.`;
+}
+
+/**
+ * Calculate cost from real API usage data.
+ */
+function calculateCost(usage) {
+  const inputTokens = usage.input_tokens || 0;
+  const cachedTokens = usage.input_tokens_details?.cached_tokens || 0;
+  const uncachedInput = inputTokens - cachedTokens;
+  const outputTokens = usage.output_tokens || 0;
+  const reasoningTokens = usage.output_tokens_details?.reasoning_tokens || 0;
+  const totalTokens = usage.total_tokens || 0;
+
+  const cost =
+    (uncachedInput / 1_000_000) * MODEL_PRICING.input +
+    (cachedTokens / 1_000_000) * MODEL_PRICING.cachedInput +
+    (outputTokens / 1_000_000) * MODEL_PRICING.output;
+
+  return {
+    cost,
+    inputTokens,
+    cachedTokens,
+    uncachedInput,
+    outputTokens,
+    reasoningTokens,
+    totalTokens,
+  };
+}
+
+/**
+ * Rough cost estimate before making a request.
+ */
+function estimateCost(estimatedInputTokens, estimatedOutputTokens = 200) {
+  return (
+    (estimatedInputTokens / 1_000_000) * MODEL_PRICING.input +
+    (estimatedOutputTokens / 1_000_000) * MODEL_PRICING.output
+  );
+}
+
+/**
+ * Format structured response into conventional commit message string.
+ */
+function formatCommitMessage(parsed) {
+  const lines = [parsed.title];
+  if (parsed.body && parsed.body.length > 0) {
+    lines.push("");
+    for (const point of parsed.body) {
+      lines.push(`- ${point}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Extract parsed content from Structured Outputs response.
+ * Handles refusals gracefully.
+ */
+function extractParsedContent(response) {
+  for (const output of response.output) {
+    if (output.type !== "message") continue;
+    for (const item of output.content) {
+      if (item.type === "refusal") {
+        throw new Error(`Model refused: ${item.refusal}`);
+      }
+      if (item.parsed) {
+        return item.parsed;
+      }
+    }
+  }
+  throw new Error("Could not parse structured response.");
+}
+
+/**
+ * Generate a commit message via OpenAI Responses API with Structured Outputs.
+ * Returns { message, usage }.
+ */
+async function generateCommitMessage(
+  diff,
+  filesInfo,
+  context = {},
+  extraInstruction = "",
+) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw new Error("OPENAI_API_KEY not set.");
+  }
+
+  const config = loadConfig();
+  const client = new OpenAI({ apiKey });
+
+  const systemPrompt = buildSystemPrompt(config, context) + extraInstruction;
+  const userPrompt = buildUserPrompt(filesInfo, diff);
+
+  const params = {
+    model: config.model,
+    instructions: systemPrompt,
+    input: userPrompt,
+    reasoning: { effort: "low" },
+    text: {
+      format: zodTextFormat(CommitMessage, "commit_message"),
+    },
+  };
+
+  if (config.devMode) {
+    params.store = true;
+  }
+
+  const response = await client.responses.parse(params);
+  const parsed = extractParsedContent(response);
+
+  return {
+    message: formatCommitMessage(parsed),
+    usage: response.usage || null,
+  };
+}
+
+module.exports = {
+  buildFilesInfo,
+  buildSystemPrompt,
+  buildUserPrompt,
+  generateCommitMessage,
+  calculateCost,
+  estimateCost,
+  countTokens,
+  MODEL_PRICING,
+};