gitxplain 0.1.6 → 0.1.9

package/cli/services/aiService.js

@@ -1,6 +1,7 @@
 import process from "node:process";
 import { createCacheKey, readCache, writeCache } from "./cacheService.js";
 import { buildPrompt } from "./promptService.js";
+import { appendUsageRecord, estimateCostUsd, resolvePricing } from "./usageService.js";
 
 const SUPPORTED_PROVIDERS = new Set([
   "openai",
@@ -8,9 +9,15 @@ const SUPPORTED_PROVIDERS = new Set([
   "openrouter",
   "gemini",
   "ollama",
-  "chutes"
+  "chutes",
+  "anthropic",
+  "mistral",
+  "azure-openai"
 ]);
 const SYSTEM_PROMPT = "You explain Git commits clearly and accurately for developers.";
+const REQUEST_TIMEOUT_MS = 30000;
+const REQUEST_RETRIES = 2;
+const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
 
 export function getProviderConfig(providerOverride, modelOverride) {
   const provider = (providerOverride ?? process.env.LLM_PROVIDER ?? "openai").toLowerCase();
@@ -71,6 +78,36 @@ export function getProviderConfig(providerOverride, modelOverride) {
     };
   }
 
+  if (provider === "anthropic") {
+    return {
+      provider,
+      apiKey: process.env.ANTHROPIC_API_KEY,
+      baseUrl: process.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com/v1",
+      model: modelOverride ?? process.env.ANTHROPIC_MODEL ?? process.env.LLM_MODEL ?? "claude-3-5-haiku-latest"
+    };
+  }
+
+  if (provider === "mistral") {
+    return {
+      provider,
+      apiKey: process.env.MISTRAL_API_KEY,
+      baseUrl: process.env.MISTRAL_BASE_URL ?? "https://api.mistral.ai/v1",
+      model: modelOverride ?? process.env.MISTRAL_MODEL ?? process.env.LLM_MODEL ?? "mistral-small-latest"
+    };
+  }
+
+  if (provider === "azure-openai") {
+    const deployment = process.env.AZURE_OPENAI_DEPLOYMENT ?? modelOverride ?? process.env.AZURE_OPENAI_MODEL ?? process.env.LLM_MODEL;
+    return {
+      provider,
+      apiKey: process.env.AZURE_OPENAI_API_KEY,
+      baseUrl: process.env.AZURE_OPENAI_BASE_URL,
+      model: process.env.AZURE_OPENAI_MODEL ?? deployment,
+      deployment,
+      apiVersion: process.env.AZURE_OPENAI_API_VERSION ?? "2024-10-21"
+    };
+  }
+
   return {
     provider,
     apiKey: process.env.OLLAMA_API_KEY ?? "ollama",
@@ -84,16 +121,32 @@ export function validateProviderConfig(config) {
     throw new Error(`No model configured for provider "${config.provider}".`);
   }
 
+  if (config.provider === "azure-openai") {
+    if (!config.baseUrl) {
+      throw new Error('Missing base URL for provider "azure-openai". Set AZURE_OPENAI_BASE_URL.');
+    }
+
+    if (!config.deployment) {
+      throw new Error('Missing deployment for provider "azure-openai". Set AZURE_OPENAI_DEPLOYMENT.');
+    }
+  }
+
   if (config.provider !== "ollama" && !config.apiKey) {
     throw new Error(`Missing API key for provider "${config.provider}".`);
   }
 }
 
 function buildOpenAICompatibleHeaders(config) {
-  const headers = {
-    "Content-Type": "application/json",
-    Authorization: `Bearer ${config.apiKey}`
-  };
+  const headers =
+    config.provider === "azure-openai"
+      ? {
+          "Content-Type": "application/json",
+          "api-key": config.apiKey
+        }
+      : {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${config.apiKey}`
+        };
 
   if (config.provider === "openrouter") {
     headers["HTTP-Referer"] = process.env.OPENROUTER_SITE_URL ?? "https://github.com";
@@ -119,6 +172,61 @@ function extractGeminiText(data) {
     .join("\n");
 }
 
+function extractAnthropicContent(data) {
+  return (data.content ?? [])
+    .filter((item) => item?.type === "text" && typeof item.text === "string")
+    .map((item) => item.text)
+    .join("\n")
+    .trim();
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isRetryableError(error) {
+  return error?.name === "AbortError" || error?.cause?.code === "UND_ERR_CONNECT_TIMEOUT";
+}
+
+export async function fetchWithRetry(url, init, options = {}) {
+  const retries = options.retries ?? REQUEST_RETRIES;
+  const timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
+
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error("Request timed out")), timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: controller.signal
+      });
+      clearTimeout(timeout);
+
+      if (RETRYABLE_STATUS_CODES.has(response.status) && attempt < retries) {
+        await sleep(250 * (attempt + 1));
+        continue;
+      }
+
+      return response;
+    } catch (error) {
+      clearTimeout(timeout);
+
+      if (attempt >= retries || !isRetryableError(error)) {
+        if (error?.name === "AbortError") {
+          throw new Error(`Request timed out after ${timeoutMs}ms.`);
+        }
+
+        throw error;
+      }
+
+      await sleep(250 * (attempt + 1));
+    }
+  }
+
+  throw new Error("Request failed after retries.");
+}
+
 async function consumeSseStream(response, getChunkText, onChunk) {
   const reader = response.body?.getReader();
   if (!reader) {
@@ -151,7 +259,13 @@ async function consumeSseStream(response, getChunkText, onChunk) {
           continue;
         }
 
-        const parsed = JSON.parse(line);
+        let parsed;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          continue;
+        }
+
         const chunkText = getChunkText(parsed);
         if (!chunkText) {
           continue;
@@ -168,21 +282,102 @@ async function consumeSseStream(response, getChunkText, onChunk) {
 
 async function requestOpenAICompatible(config, prompt, options) {
   const startedAt = Date.now();
-  const response = await fetch(`${config.baseUrl}/chat/completions`, {
+  const endpoint =
+    config.provider === "azure-openai"
+      ? `${config.baseUrl}/openai/deployments/${encodeURIComponent(config.deployment)}/chat/completions?api-version=${encodeURIComponent(config.apiVersion)}`
+      : `${config.baseUrl}/chat/completions`;
+  const body = {
+    messages: [
+      {
+        role: "system",
+        content: SYSTEM_PROMPT
+      },
+      {
+        role: "user",
+        content: prompt
+      }
+    ],
+    temperature: 0.2,
+    stream: options.stream === true
+  };
+
+  if (config.provider !== "azure-openai") {
+    body.model = config.model;
+  }
+
+  const response = await fetchWithRetry(endpoint, {
     method: "POST",
     headers: buildOpenAICompatibleHeaders(config),
+    body: JSON.stringify(body)
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`${config.provider} request failed (${response.status}): ${errorText}`);
+  }
+
+  if (options.stream) {
+    const explanation = await consumeSseStream(
+      response,
+      (data) => {
+        const content = data.choices?.[0]?.delta?.content;
+        if (typeof content === "string") {
+          return content;
+        }
+
+        if (Array.isArray(content)) {
+          return content.map((item) => item.text ?? "").join("");
+        }
+
+        return "";
+      },
+      options.onChunk
+    );
+
+    return {
+      explanation,
+      responseMeta: {
+        provider: config.provider,
+        model: config.model,
+        cacheHit: false,
+        latencyMs: Date.now() - startedAt,
+        usage: null
+      }
+    };
+  }
+
+  const data = await response.json();
+  return {
+    explanation: extractOpenAIContent(data),
+    responseMeta: {
+      provider: config.provider,
+      model: config.model,
+      cacheHit: false,
+      latencyMs: Date.now() - startedAt,
+      usage: extractUsage(data)
+    }
+  };
+}
+
+async function requestAnthropic(config, prompt, options) {
+  const startedAt = Date.now();
+  const response = await fetchWithRetry(`${config.baseUrl}/messages`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": config.apiKey,
+      "anthropic-version": "2023-06-01"
+    },
     body: JSON.stringify({
       model: config.model,
+      system: SYSTEM_PROMPT,
       messages: [
-        {
-          role: "system",
-          content: SYSTEM_PROMPT
-        },
         {
           role: "user",
           content: prompt
         }
       ],
+      max_tokens: 2048,
       temperature: 0.2,
       stream: options.stream === true
     })
@@ -190,20 +385,15 @@ async function requestOpenAICompatible(config, prompt, options) {
 
   if (!response.ok) {
     const errorText = await response.text();
-    throw new Error(`${config.provider} request failed (${response.status}): ${errorText}`);
+    throw new Error(`anthropic request failed (${response.status}): ${errorText}`);
   }
 
   if (options.stream) {
     const explanation = await consumeSseStream(
       response,
       (data) => {
-        const content = data.choices?.[0]?.delta?.content;
-        if (typeof content === "string") {
-          return content;
-        }
-
-        if (Array.isArray(content)) {
-          return content.map((item) => item.text ?? "").join("");
+        if (data.type === "content_block_delta") {
+          return data.delta?.text ?? "";
         }
 
         return "";
@@ -225,13 +415,13 @@ async function requestOpenAICompatible(config, prompt, options) {
 
   const data = await response.json();
   return {
-    explanation: extractOpenAIContent(data),
+    explanation: extractAnthropicContent(data) || "No explanation returned by the model.",
     responseMeta: {
       provider: config.provider,
       model: config.model,
       cacheHit: false,
       latencyMs: Date.now() - startedAt,
-      usage: extractUsage(data)
+      usage: data.usage ?? null
     }
   };
 }
@@ -242,7 +432,7 @@ async function requestGemini(config, prompt, options) {
     ? `${config.baseUrl}/models/${config.model}:streamGenerateContent?alt=sse&key=${encodeURIComponent(config.apiKey)}`
     : `${config.baseUrl}/models/${config.model}:generateContent?key=${encodeURIComponent(config.apiKey)}`;
 
-  const response = await fetch(endpoint, {
+  const response = await fetchWithRetry(endpoint, {
     method: "POST",
     headers: {
       "Content-Type": "application/json"
@@ -309,6 +499,7 @@ export async function generateExplanation({
   providerOverride,
   modelOverride,
   maxDiffLines,
+  noCache = false,
   stream = false,
   onChunk = null,
   onStart = null
@@ -330,7 +521,7 @@ export async function generateExplanation({
     model: config.model,
     prompt
   });
-  const cached = readCache(cacheKey);
+  const cached = noCache ? null : readCache(cacheKey);
 
   if (cached) {
     return {
@@ -347,13 +538,28 @@ export async function generateExplanation({
   const result =
     config.provider === "gemini"
       ? await requestGemini(config, prompt, requestOptions)
-      : await requestOpenAICompatible(config, prompt, requestOptions);
-
-  writeCache(cacheKey, {
-    explanation: result.explanation,
-    responseMeta: result.responseMeta
+      : config.provider === "anthropic"
+        ? await requestAnthropic(config, prompt, requestOptions)
+        : await requestOpenAICompatible(config, prompt, requestOptions);
+
+  const estimatedCostUsd = estimateCostUsd(result.responseMeta.usage, resolvePricing(config));
+  result.responseMeta.estimatedCostUsd = estimatedCostUsd;
+
+  appendUsageRecord({
+    provider: result.responseMeta.provider,
+    model: result.responseMeta.model,
+    usage: result.responseMeta.usage,
+    latencyMs: result.responseMeta.latencyMs,
+    estimatedCostUsd
   });
 
+  if (!noCache) {
+    writeCache(cacheKey, {
+      explanation: result.explanation,
+      responseMeta: result.responseMeta
+    });
+  }
+
   return {
     explanation: result.explanation,
     promptMeta,

package/cli/services/cacheService.js

@@ -1,12 +1,19 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createHash } from "node:crypto";
 
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_CACHE_FILES = 200;
+
 function getCacheDir() {
   return path.join(os.homedir(), ".gitxplain", "cache");
 }
 
+export function getCacheDirectory() {
+  return getCacheDir();
+}
+
 export function createCacheKey(parts) {
   const hash = createHash("sha256");
   hash.update(JSON.stringify(parts));
@@ -17,6 +24,52 @@ function getCachePath(cacheKey) {
   return path.join(getCacheDir(), `${cacheKey}.json`);
 }
 
+function listCacheEntries() {
+  const dir = getCacheDir();
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".json"))
+    .map((name) => {
+      const filePath = path.join(dir, name);
+      const stats = statSync(filePath);
+      return {
+        filePath,
+        mtimeMs: stats.mtimeMs,
+        sizeBytes: stats.size
+      };
+    })
+    .sort((left, right) => left.mtimeMs - right.mtimeMs);
+}
+
+function isExpired(mtimeMs) {
+  return Date.now() - mtimeMs > CACHE_TTL_MS;
+}
+
+function pruneCache() {
+  const entries = listCacheEntries();
+
+  for (const entry of entries.filter((item) => isExpired(item.mtimeMs))) {
+    try {
+      unlinkSync(entry.filePath);
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }
+
+  const remaining = listCacheEntries();
+  const overflowCount = Math.max(0, remaining.length - MAX_CACHE_FILES);
+  for (const entry of remaining.slice(0, overflowCount)) {
+    try {
+      unlinkSync(entry.filePath);
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }
+}
+
 export function readCache(cacheKey) {
   const filePath = getCachePath(cacheKey);
   if (!existsSync(filePath)) {
@@ -24,6 +77,12 @@ export function readCache(cacheKey) {
   }
 
   try {
+    const stats = statSync(filePath);
+    if (isExpired(stats.mtimeMs)) {
+      unlinkSync(filePath);
+      return null;
+    }
+
     return JSON.parse(readFileSync(filePath, "utf8"));
   } catch {
     return null;
@@ -34,4 +93,36 @@ export function writeCache(cacheKey, value) {
   const dir = getCacheDir();
   mkdirSync(dir, { recursive: true });
   writeFileSync(getCachePath(cacheKey), JSON.stringify(value, null, 2), "utf8");
+  pruneCache();
+}
+
+export function clearCache() {
+  const dir = getCacheDir();
+  const entries = listCacheEntries();
+
+  if (existsSync(dir)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+
+  return entries.length;
+}
+
+export function getCacheStats() {
+  const entries = listCacheEntries();
+
+  if (entries.length === 0) {
+    return {
+      entryCount: 0,
+      totalSizeBytes: 0,
+      oldestEntryIso: null,
+      newestEntryIso: null
+    };
+  }
+
+  return {
+    entryCount: entries.length,
+    totalSizeBytes: entries.reduce((sum, entry) => sum + entry.sizeBytes, 0),
+    oldestEntryIso: new Date(entries[0].mtimeMs).toISOString(),
+    newestEntryIso: new Date(entries[entries.length - 1].mtimeMs).toISOString()
+  };
 }

package/cli/services/clipboardService.js

@@ -23,6 +23,11 @@ export function copyToClipboard(text) {
     runClipboardCommand("wl-copy", [], text);
     return;
   } catch {
-    runClipboardCommand("xclip", ["-selection", "clipboard"], text);
+    try {
+      runClipboardCommand("xclip", ["-selection", "clipboard"], text);
+      return;
+    } catch {
+      throw new Error("Clipboard copy failed on Linux. Install `wl-copy` or `xclip` and try again.");
+    }
   }
 }

package/cli/services/colorSupport.js

@@ -0,0 +1,31 @@
+import process from "node:process";
+
+export const ANSI = {
+  reset: "\u001b[0m",
+  bold: "\u001b[1m",
+  cyan: "\u001b[36m",
+  yellow: "\u001b[33m",
+  green: "\u001b[32m",
+  red: "\u001b[31m",
+  gray: "\u001b[90m"
+};
+
+export function supportsColor() {
+  if (process.env.FORCE_COLOR != null && process.env.FORCE_COLOR !== "0") {
+    return true;
+  }
+
+  if (process.env.NO_COLOR != null) {
+    return false;
+  }
+
+  return Boolean(process.stdout?.isTTY);
+}
+
+export function colorize(text, color) {
+  if (!supportsColor()) {
+    return text;
+  }
+
+  return `${color}${text}${ANSI.reset}`;
+}

package/cli/services/commitService.js

@@ -1,4 +1,3 @@
-import process from "node:process";
 import {
   deletePaths,
   fetchWorkingTreeData,
@@ -18,29 +17,10 @@ import {
   resolveTreeSha,
   writeCurrentIndexTree
 } from "./gitService.js";
-
-const ANSI = {
-  reset: "\u001b[0m",
-  bold: "\u001b[1m",
-  cyan: "\u001b[36m",
-  yellow: "\u001b[33m",
-  green: "\u001b[32m"
-};
-
-function supportsColor() {
-  return Boolean(process.stdout?.isTTY) && process.env.NO_COLOR == null;
-}
-
-function colorize(text, color) {
-  if (!supportsColor()) {
-    return text;
-  }
-
-  return `${color}${text}${ANSI.reset}`;
-}
+import { ANSI, colorize } from "./colorSupport.js";
 
 function extractJsonPayload(explanation) {
-  const fencedMatch = explanation.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+  const fencedMatch = explanation.match(/```[A-Za-z0-9_-]*\s*([\s\S]*?)\s*```/);
   if (fencedMatch) {
     return fencedMatch[1].trim();
   }
@@ -59,6 +39,104 @@ function isNonEmptyString(value) {
   return typeof value === "string" && value.trim() !== "";
 }
 
+function stripMarkdown(text) {
+  return text
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/__([^_]+)__/g, "$1")
+    .replace(/\*([^*]+)\*/g, "$1")
+    .replace(/_([^_]+)_/g, "$1")
+    .trim();
+}
+
+function parseFilesLine(value) {
+  return value
+    .split(/[,\n]/)
+    .map((file) => stripMarkdown(file).trim())
+    .filter(Boolean);
+}
+
+function parseTextCommitPlan(explanation) {
+  const lines = explanation.split("\n").map((line) => line.trimEnd());
+  const commits = [];
+  let workingTreeSummary = null;
+  let reasonToCommit = null;
+  let currentCommit = null;
+
+  const pushCurrentCommit = () => {
+    if (!currentCommit) {
+      return;
+    }
+
+    commits.push({
+      order: currentCommit.order,
+      message: currentCommit.message,
+      files: currentCommit.files,
+      description: currentCommit.description
+    });
+    currentCommit = null;
+  };
+
+  for (const rawLine of lines) {
+    const line = stripMarkdown(rawLine.trim());
+    if (line === "") {
+      continue;
+    }
+
+    if (/^(working tree summary|summary)\s*:/i.test(line)) {
+      workingTreeSummary = line.replace(/^(working tree summary|summary)\s*:/i, "").trim();
+      continue;
+    }
+
+    if (/^(reason to commit|reason)\s*:/i.test(line)) {
+      reasonToCommit = line.replace(/^(reason to commit|reason)\s*:/i, "").trim() || null;
+      continue;
+    }
+
+    const commitMatch = line.match(/^(?:[-*]\s*)?(\d+)\.\s+(.+)$/);
+    if (commitMatch) {
+      pushCurrentCommit();
+      currentCommit = {
+        order: Number.parseInt(commitMatch[1], 10),
+        message: commitMatch[2].trim(),
+        files: [],
+        description: ""
+      };
+      continue;
+    }
+
+    if (!currentCommit) {
+      continue;
+    }
+
+    if (/^files?\s*:/i.test(line)) {
+      currentCommit.files.push(...parseFilesLine(line.replace(/^files?\s*:/i, "")));
+      continue;
+    }
+
+    if (/^(why|description)\s*:/i.test(line)) {
+      currentCommit.description = line.replace(/^(why|description)\s*:/i, "").trim();
+      continue;
+    }
+
+    if (currentCommit.description) {
+      currentCommit.description = `${currentCommit.description} ${line}`.trim();
+    }
+  }
+
+  pushCurrentCommit();
+
+  if (!workingTreeSummary || commits.length === 0) {
+    throw new Error("Failed to parse commit plan: no JSON object found in model response.");
+  }
+
+  return {
+    working_tree_summary: workingTreeSummary,
+    reason_to_commit: reasonToCommit,
+    commits
+  };
+}
+
 function validateCommitEntry(entry, index) {
   if (typeof entry !== "object" || entry == null || Array.isArray(entry)) {
     throw new Error(`Failed to parse commit plan: commit ${index + 1} must be an object.`);
@@ -257,7 +335,11 @@ export function parseCommitPlan(explanation) {
   try {
     parsed = JSON.parse(extractJsonPayload(explanation));
   } catch (error) {
-    throw new Error(`Failed to parse commit plan JSON: ${error.message}`);
+    try {
+      parsed = parseTextCommitPlan(explanation);
+    } catch {
+      throw new Error(`Failed to parse commit plan JSON: ${error.message}`);
+    }
   }
 
   if (typeof parsed !== "object" || parsed == null || Array.isArray(parsed)) {