gitxplain 0.1.0

package/cli/services/aiService.js

@@ -0,0 +1,362 @@
+import process from "node:process";
+import { createCacheKey, readCache, writeCache } from "./cacheService.js";
+import { buildPrompt } from "./promptService.js";
+
+const SUPPORTED_PROVIDERS = new Set([
+  "openai",
+  "groq",
+  "openrouter",
+  "gemini",
+  "ollama",
+  "chutes"
+]);
+const SYSTEM_PROMPT = "You explain Git commits clearly and accurately for developers.";
+
+function getProviderConfig(providerOverride, modelOverride) {
+  const provider = (providerOverride ?? process.env.LLM_PROVIDER ?? "openai").toLowerCase();
+
+  if (!SUPPORTED_PROVIDERS.has(provider)) {
+    throw new Error(
+      `Unsupported provider "${provider}". Supported providers: ${[...SUPPORTED_PROVIDERS].join(", ")}.`
+    );
+  }
+
+  if (provider === "openai") {
+    return {
+      provider,
+      apiKey: process.env.OPENAI_API_KEY,
+      baseUrl: process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1",
+      model: modelOverride ?? process.env.OPENAI_MODEL ?? process.env.LLM_MODEL ?? "gpt-4.1-mini"
+    };
+  }
+
+  if (provider === "groq") {
+    return {
+      provider,
+      apiKey: process.env.GROQ_API_KEY,
+      baseUrl: process.env.GROQ_BASE_URL ?? "https://api.groq.com/openai/v1",
+      model: modelOverride ?? process.env.GROQ_MODEL ?? process.env.LLM_MODEL ?? "llama-3.3-70b-versatile"
+    };
+  }
+
+  if (provider === "openrouter") {
+    return {
+      provider,
+      apiKey: process.env.OPENROUTER_API_KEY,
+      baseUrl: process.env.OPENROUTER_BASE_URL ?? "https://openrouter.ai/api/v1",
+      model: modelOverride ?? process.env.OPENROUTER_MODEL ?? process.env.LLM_MODEL ?? "openai/gpt-4.1-mini"
+    };
+  }
+
+  if (provider === "gemini") {
+    return {
+      provider,
+      apiKey: process.env.GEMINI_API_KEY,
+      baseUrl:
+        process.env.GEMINI_BASE_URL ?? "https://generativelanguage.googleapis.com/v1beta",
+      model: modelOverride ?? process.env.GEMINI_MODEL ?? process.env.LLM_MODEL ?? "gemini-2.5-flash"
+    };
+  }
+
+  if (provider === "chutes") {
+    return {
+      provider,
+      apiKey: process.env.CHUTES_API_KEY,
+      baseUrl: process.env.CHUTES_BASE_URL ?? "https://llm.chutes.ai/v1",
+      model:
+        modelOverride ??
+        process.env.CHUTES_MODEL ??
+        process.env.LLM_MODEL ??
+        "deepseek-ai/DeepSeek-V3-0324"
+    };
+  }
+
+  return {
+    provider,
+    apiKey: process.env.OLLAMA_API_KEY ?? "ollama",
+    baseUrl: process.env.OLLAMA_BASE_URL ?? "http://127.0.0.1:11434/v1",
+    model: modelOverride ?? process.env.OLLAMA_MODEL ?? process.env.LLM_MODEL ?? "llama3.2"
+  };
+}
+
+function validateProviderConfig(config) {
+  if (!config.model) {
+    throw new Error(`No model configured for provider "${config.provider}".`);
+  }
+
+  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}`
+  };
+
+  if (config.provider === "openrouter") {
+    headers["HTTP-Referer"] = process.env.OPENROUTER_SITE_URL ?? "https://github.com";
+    headers["X-Title"] = process.env.OPENROUTER_APP_NAME ?? "gitxplain";
+  }
+
+  return headers;
+}
+
+function extractUsage(data) {
+  return data.usage ?? null;
+}
+
+function extractOpenAIContent(data) {
+  return data.choices?.[0]?.message?.content?.trim() || "No explanation returned by the model.";
+}
+
+function extractGeminiText(data) {
+  const parts = data.candidates?.[0]?.content?.parts ?? [];
+  return parts
+    .map((part) => part.text)
+    .filter(Boolean)
+    .join("\n");
+}
+
+async function consumeSseStream(response, getChunkText, onChunk) {
+  const reader = response.body?.getReader();
+  if (!reader) {
+    throw new Error("Streaming is not supported by this runtime.");
+  }
+
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let fullText = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+
+    buffer += decoder.decode(value, { stream: true });
+    const events = buffer.split("\n\n");
+    buffer = events.pop() ?? "";
+
+    for (const event of events) {
+      const dataLines = event
+        .split("\n")
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trim())
+        .filter(Boolean);
+
+      for (const line of dataLines) {
+        if (line === "[DONE]") {
+          continue;
+        }
+
+        const parsed = JSON.parse(line);
+        const chunkText = getChunkText(parsed);
+        if (!chunkText) {
+          continue;
+        }
+
+        fullText += chunkText;
+        onChunk?.(chunkText);
+      }
+    }
+  }
+
+  return fullText.trim();
+}
+
+async function requestOpenAICompatible(config, prompt, options) {
+  const startedAt = Date.now();
+  const response = await fetch(`${config.baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: buildOpenAICompatibleHeaders(config),
+    body: JSON.stringify({
+      model: config.model,
+      messages: [
+        {
+          role: "system",
+          content: SYSTEM_PROMPT
+        },
+        {
+          role: "user",
+          content: prompt
+        }
+      ],
+      temperature: 0.2,
+      stream: options.stream === true
+    })
+  });
+
+  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 requestGemini(config, prompt, options) {
+  const startedAt = Date.now();
+  const endpoint = options.stream
+    ? `${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, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      systemInstruction: {
+        parts: [
+          {
+            text: SYSTEM_PROMPT
+          }
+        ]
+      },
+      contents: [
+        {
+          role: "user",
+          parts: [
+            {
+              text: prompt
+            }
+          ]
+        }
+      ],
+      generationConfig: {
+        temperature: 0.2
+      }
+    })
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`gemini request failed (${response.status}): ${errorText}`);
+  }
+
+  if (options.stream) {
+    const explanation = await consumeSseStream(response, extractGeminiText, 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: extractGeminiText(data).trim() || "No explanation returned by the model.",
+    responseMeta: {
+      provider: config.provider,
+      model: config.model,
+      cacheHit: false,
+      latencyMs: Date.now() - startedAt,
+      usage: data.usageMetadata ?? null
+    }
+  };
+}
+
+export async function generateExplanation({
+  mode,
+  commitData,
+  providerOverride,
+  modelOverride,
+  maxDiffLines,
+  stream = false,
+  onChunk = null,
+  onStart = null
+}) {
+  const config = getProviderConfig(providerOverride, modelOverride);
+  validateProviderConfig(config);
+
+  const { prompt, promptMeta } = buildPrompt(mode, commitData, { maxDiffLines });
+  onStart?.({
+    promptMeta,
+    provider: config.provider,
+    model: config.model
+  });
+
+  const cacheKey = createCacheKey({
+    targetRef: commitData.targetRef,
+    mode,
+    provider: config.provider,
+    model: config.model,
+    prompt
+  });
+  const cached = readCache(cacheKey);
+
+  if (cached) {
+    return {
+      explanation: cached.explanation,
+      promptMeta,
+      responseMeta: {
+        ...cached.responseMeta,
+        cacheHit: true
+      }
+    };
+  }
+
+  const requestOptions = { stream, onChunk };
+  const result =
+    config.provider === "gemini"
+      ? await requestGemini(config, prompt, requestOptions)
+      : await requestOpenAICompatible(config, prompt, requestOptions);
+
+  writeCache(cacheKey, {
+    explanation: result.explanation,
+    responseMeta: result.responseMeta
+  });
+
+  return {
+    explanation: result.explanation,
+    promptMeta,
+    responseMeta: result.responseMeta
+  };
+}

package/cli/services/cacheService.js

@@ -0,0 +1,37 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+function getCacheDir() {
+  return path.join(os.homedir(), ".gitxplain", "cache");
+}
+
+export function createCacheKey(parts) {
+  const hash = createHash("sha256");
+  hash.update(JSON.stringify(parts));
+  return hash.digest("hex");
+}
+
+function getCachePath(cacheKey) {
+  return path.join(getCacheDir(), `${cacheKey}.json`);
+}
+
+export function readCache(cacheKey) {
+  const filePath = getCachePath(cacheKey);
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeCache(cacheKey, value) {
+  const dir = getCacheDir();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(getCachePath(cacheKey), JSON.stringify(value, null, 2), "utf8");
+}

package/cli/services/clipboardService.js

@@ -0,0 +1,28 @@
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+
+function runClipboardCommand(command, args, input) {
+  execFileSync(command, args, {
+    input,
+    stdio: ["pipe", "ignore", "ignore"]
+  });
+}
+
+export function copyToClipboard(text) {
+  if (process.platform === "darwin") {
+    runClipboardCommand("pbcopy", [], text);
+    return;
+  }
+
+  if (process.platform === "win32") {
+    runClipboardCommand("clip.exe", [], text);
+    return;
+  }
+
+  try {
+    runClipboardCommand("wl-copy", [], text);
+    return;
+  } catch {
+    runClipboardCommand("xclip", ["-selection", "clipboard"], text);
+  }
+}

package/cli/services/configService.js

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function readJsonConfig(filePath) {
+  if (!existsSync(filePath)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Failed to parse config file ${filePath}: ${error.message}`);
+  }
+}
+
+export function loadConfig(cwd) {
+  const homeDir = os.homedir();
+  const userConfigPath = path.join(homeDir, ".gitxplain", "config.json");
+  const projectConfigPath = path.join(cwd, ".gitxplainrc");
+  const projectJsonConfigPath = path.join(cwd, ".gitxplainrc.json");
+
+  return {
+    ...readJsonConfig(userConfigPath),
+    ...readJsonConfig(projectConfigPath),
+    ...readJsonConfig(projectJsonConfigPath)
+  };
+}

package/cli/services/gitService.js

@@ -0,0 +1,132 @@
+import { execFileSync } from "node:child_process";
+
+export function runGitCommand(args, cwd) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }).trim();
+  } catch (error) {
+    const stderr = error.stderr?.toString().trim();
+    throw new Error(stderr || `Git command failed: git ${args.join(" ")}`);
+  }
+}
+
+export function isGitRepository(cwd) {
+  try {
+    return runGitCommand(["rev-parse", "--is-inside-work-tree"], cwd) === "true";
+  } catch {
+    return false;
+  }
+}
+
+function parseFilesChanged(raw) {
+  return raw
+    .split("\n")
+    .map((file) => file.trim())
+    .filter(Boolean);
+}
+
+function parseStatsLine(statsRaw) {
+  return (
+    statsRaw
+      .split("\n")
+      .map((line) => line.trim())
+      .find((line) => /changed|insertions?\(\+\)|deletions?\(-\)/.test(line)) ??
+    "No change statistics available."
+  );
+}
+
+function parseCommitLog(logRaw) {
+  return logRaw
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const [hash, subject, body = ""] = line.split("\u001f");
+      return { hash, subject, body };
+    });
+}
+
+function buildCommitMessage(commits) {
+  return commits
+    .map((commit) => `${commit.hash.slice(0, 7)} ${commit.subject}${commit.body ? `\n${commit.body}` : ""}`)
+    .join("\n\n");
+}
+
+function isRangeRef(ref) {
+  return ref.includes("..");
+}
+
+export function getDefaultBaseRef(cwd) {
+  for (const candidate of ["main", "master", "origin/main", "origin/master"]) {
+    try {
+      runGitCommand(["rev-parse", "--verify", candidate], cwd);
+      return candidate;
+    } catch {
+      continue;
+    }
+  }
+
+  throw new Error("Could not detect a default base branch. Pass --branch <base-ref> explicitly.");
+}
+
+export function buildBranchRange(baseRef, cwd) {
+  const mergeBase = runGitCommand(["merge-base", baseRef, "HEAD"], cwd);
+  return `${mergeBase}..HEAD`;
+}
+
+function fetchSingleCommitData(commitId, cwd, runner) {
+  const commitMessage = runner(["log", "-1", "--pretty=format:%B", commitId], cwd);
+  const diff = runner(["diff", `${commitId}^!`], cwd);
+  const filesChangedRaw = runner(["show", "--pretty=format:", "--name-only", commitId], cwd);
+  const statsRaw = runner(["show", "--stat", "--oneline", "--format=%h %s", commitId], cwd);
+  const subject = runner(["log", "-1", "--pretty=format:%s", commitId], cwd);
+
+  return {
+    analysisType: "commit",
+    targetRef: commitId,
+    displayRef: commitId,
+    commitId,
+    commitCount: 1,
+    commits: [{ hash: commitId, subject, body: commitMessage }],
+    commitMessage,
+    diff,
+    filesChanged: parseFilesChanged(filesChangedRaw),
+    stats: parseStatsLine(statsRaw)
+  };
+}
+
+function fetchRangeData(rangeRef, cwd, runner) {
+  const diff = runner(["diff", rangeRef], cwd);
+  const filesChangedRaw = runner(["diff", "--name-only", rangeRef], cwd);
+  const statsRaw = runner(["diff", "--stat", rangeRef], cwd);
+  const commitLogRaw = runner(
+    ["log", "--reverse", "--pretty=format:%H%x1f%s%x1f%B", rangeRef],
+    cwd
+  );
+
+  const commits = parseCommitLog(commitLogRaw);
+  if (commits.length === 0) {
+    throw new Error(`No commits found in range ${rangeRef}`);
+  }
+
+  return {
+    analysisType: "range",
+    targetRef: rangeRef,
+    displayRef: rangeRef,
+    commitId: null,
+    commitCount: commits.length,
+    commits,
+    commitMessage: buildCommitMessage(commits),
+    diff,
+    filesChanged: parseFilesChanged(filesChangedRaw),
+    stats: parseStatsLine(statsRaw)
+  };
+}
+
+export function fetchCommitData(targetRef, cwd, runner = runGitCommand) {
+  return isRangeRef(targetRef)
+    ? fetchRangeData(targetRef, cwd, runner)
+    : fetchSingleCommitData(targetRef, cwd, runner);
+}

package/cli/services/hookService.js

@@ -0,0 +1,21 @@
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { runGitCommand } from "./gitService.js";
+
+export function installHook({ cwd, hookName = "post-commit" }) {
+  const gitDir = runGitCommand(["rev-parse", "--git-dir"], cwd);
+  const hookDir = path.resolve(cwd, gitDir, "hooks");
+  const outputDir = path.resolve(cwd, gitDir, "gitxplain");
+  const hookPath = path.join(hookDir, hookName);
+
+  mkdirSync(hookDir, { recursive: true });
+  mkdirSync(outputDir, { recursive: true });
+
+  const script = `#!/bin/sh
+gitxplain HEAD --summary --markdown --quiet > "${path.join(outputDir, "last-explanation.md")}" 2>/dev/null || true
+`;
+
+  writeFileSync(hookPath, script, "utf8");
+  chmodSync(hookPath, 0o755);
+  return hookPath;
+}