@synmux/claude-commit 0.1.0

package/src/diff.ts

@@ -0,0 +1,154 @@
+/**
+ * Splitting a unified git diff into chunks that fit a character budget.
+ *
+ * The packer is structure-aware: it prefers to break on file boundaries, then
+ * on hunk (`@@`) boundaries, and only falls back to raw line splitting for a
+ * single hunk that is itself larger than the budget. When a file section is
+ * split, its header (`diff --git ... / --- / +++`) is repeated at the top of
+ * every piece so each chunk remains a self-contained, interpretable diff.
+ */
+
+const FILE_HEADER = "diff --git ";
+const HUNK_HEADER = "@@";
+
+/**
+ * Minimum per-piece character budget (after the repeated file header) below
+ * which we stop trying to subdivide a section. This guards against a
+ * misconfigured tiny `maxChars`, or a pathologically large file header,
+ * driving the line-splitter's budget to zero and shattering a hunk into
+ * one-character pieces — which would otherwise spawn a model request per
+ * character.
+ */
+const MIN_SPLIT_BUDGET = 64;
+
+/** Split a full diff into per-file sections. */
+function splitFileSections(diff: string): string[] {
+  const lines = diff.split("\n");
+  const sections: string[] = [];
+  let current: string[] = [];
+  for (const line of lines) {
+    if (line.startsWith(FILE_HEADER) && current.length > 0) {
+      sections.push(current.join("\n"));
+      current = [line];
+    } else {
+      current.push(line);
+    }
+  }
+  if (current.length > 0) sections.push(current.join("\n"));
+  return sections;
+}
+
+/** Group the body of a file section (from the first `@@`) into hunks. */
+function groupHunks(bodyLines: string[]): string[] {
+  const hunks: string[] = [];
+  let current: string[] = [];
+  for (const line of bodyLines) {
+    if (line.startsWith(HUNK_HEADER) && current.length > 0) {
+      hunks.push(current.join("\n"));
+      current = [line];
+    } else {
+      current.push(line);
+    }
+  }
+  if (current.length > 0) hunks.push(current.join("\n"));
+  return hunks;
+}
+
+/** Break a string into pieces of at most `maxLen` characters, preferring line boundaries. */
+function breakByLines(text: string, maxLen: number): string[] {
+  const limit = Math.max(1, maxLen);
+  const lines = text.split("\n");
+  const pieces: string[] = [];
+  let current = "";
+  for (const line of lines) {
+    const addition = current === "" ? line.length : line.length + 1;
+    if (current !== "" && current.length + addition > limit) {
+      pieces.push(current);
+      current = "";
+    }
+    if (line.length > limit) {
+      // A single line longer than the budget: hard-split it.
+      if (current !== "") {
+        pieces.push(current);
+        current = "";
+      }
+      for (let i = 0; i < line.length; i += limit) {
+        pieces.push(line.slice(i, i + limit));
+      }
+    } else {
+      current = current === "" ? line : current + "\n" + line;
+    }
+  }
+  if (current !== "") pieces.push(current);
+  return pieces;
+}
+
+/** Break an oversized file section into units that each fit `maxChars`. */
+function breakSection(section: string, maxChars: number): string[] {
+  if (section.length <= maxChars) return [section];
+
+  const lines = section.split("\n");
+  const firstHunk = lines.findIndex((l) => l.startsWith(HUNK_HEADER));
+  if (firstHunk === -1) {
+    // No hunks to split on (binary patch, pure rename, mode change): keep whole.
+    return [section];
+  }
+
+  const header = lines.slice(0, firstHunk).join("\n");
+  const headerLen = header.length + 1; // account for the joining newline
+
+  // If there isn't room for a meaningful piece after repeating the header,
+  // keep the section whole rather than exploding it into tiny fragments.
+  if (maxChars - headerLen < MIN_SPLIT_BUDGET) return [section];
+
+  const hunks = groupHunks(lines.slice(firstHunk));
+  const units: string[] = [];
+
+  for (const hunk of hunks) {
+    if (headerLen + hunk.length <= maxChars) {
+      units.push(header + "\n" + hunk);
+    } else {
+      for (const piece of breakByLines(hunk, maxChars - headerLen)) {
+        units.push(header + "\n" + piece);
+      }
+    }
+  }
+  return units;
+}
+
+/** Greedily pack pre-fitted units into as few chunks as possible. */
+function packUnits(units: string[], maxChars: number): string[] {
+  const chunks: string[] = [];
+  let current = "";
+  for (const unit of units) {
+    if (current === "") {
+      current = unit;
+      continue;
+    }
+    if (current.length + 1 + unit.length <= maxChars) {
+      current = current + "\n" + unit;
+    } else {
+      chunks.push(current);
+      current = unit;
+    }
+  }
+  if (current !== "") chunks.push(current);
+  return chunks;
+}
+
+/**
+ * Split a unified diff into chunks no larger than `maxChars` characters.
+ *
+ * Returns an empty array for an empty diff, and a single-element array when the
+ * whole diff already fits.
+ */
+export function splitDiff(diff: string, maxChars: number): string[] {
+  if (diff.trim() === "") return [];
+  if (diff.length <= maxChars) return [diff];
+
+  const units: string[] = [];
+  for (const section of splitFileSections(diff)) {
+    units.push(...breakSection(section, maxChars));
+  }
+  return packUnits(units, maxChars);
+}

package/src/errors.ts

@@ -0,0 +1,4 @@
+/** Error type for user-facing, expected failures (printed without a stack trace). */
+export class ClaudeCommitError extends Error {
+  override name = "ClaudeCommitError";
+}

package/src/generate.ts

@@ -0,0 +1,180 @@
+/**
+ * The commit-message pipeline:
+ *
+ *   diff ──split──▶ [chunk, chunk, ...] ──summary model──▶ [summary, ...]
+ *        ──final model──▶ commit message(s)
+ *
+ * The summary model (default `sonnet[1m]`) reads each diff chunk and writes a
+ * factual summary; chunking keeps each request within the model's context
+ * window. The final model (default `haiku`) turns the summaries into the commit
+ * message(s), applying the configured formatting rules.
+ */
+import { runPrompt } from "./agent";
+import { splitDiff } from "./diff";
+import { tokensToChars } from "./tokens";
+import { ClaudeCommitError } from "./errors";
+import {
+  buildFinalSystem,
+  buildFinalUser,
+  buildSummarySystem,
+  buildSummaryUser,
+  cleanMessage,
+  extractMessages,
+  MESSAGES_SCHEMA,
+  parseOptions,
+} from "./prompts";
+import type { Config } from "./types";
+
+export interface GenerateProgress {
+  /** Called when a new phase of work begins (for spinner labels). */
+  onPhase?: (label: string) => void;
+  /** Receives streamed text of the final message as it is produced. */
+  onText?: (delta: string) => void;
+}
+
+export interface GenerateOptions {
+  /** Number of candidate messages to produce (interactive mode uses > 1). */
+  count?: number;
+  progress?: GenerateProgress;
+  abortController?: AbortController;
+}
+
+export interface GenerateResult {
+  /** Candidate commit messages (length 1 in non-interactive mode). */
+  messages: string[];
+  /** The intermediate summaries (useful for `--verbose`). */
+  summaries: string[];
+  /** Number of diff chunks the summary stage processed. */
+  chunkCount: number;
+  /** Total cost across all model calls, in USD. */
+  costUsd: number;
+}
+
+/** Run the full pipeline over a staged diff. */
+export async function generateCommit(
+  diff: string,
+  config: Config,
+  options: GenerateOptions = {},
+): Promise<GenerateResult> {
+  const { count = 1, progress = {}, abortController } = options;
+
+  const maxChars = tokensToChars(config.maxChunkTokens, config.charsPerToken);
+  const chunks = splitDiff(diff, maxChars);
+  if (chunks.length === 0) {
+    throw new ClaudeCommitError("There are no staged changes to summarize.");
+  }
+
+  // Stage 1: summarize each chunk.
+  const summarySystem = buildSummarySystem();
+  const summaries: string[] = [];
+  let costUsd = 0;
+
+  for (let i = 0; i < chunks.length; i++) {
+    progress.onPhase?.(
+      chunks.length > 1
+        ? `Reading diff (part ${i + 1}/${chunks.length})`
+        : "Reading diff",
+    );
+    const result = await runPrompt(
+      buildSummaryUser(chunks[i]!, i, chunks.length),
+      {
+        model: config.models.summary,
+        system: summarySystem,
+        allowApiKey: config.allowApiKey,
+        ...(abortController ? { abortController } : {}),
+      },
+    );
+    summaries.push(result.text);
+    costUsd += result.costUsd;
+  }
+
+  // Stage 2: write the commit message(s) from the summaries.
+  //
+  // Prefer a structured (JSON-schema) response so parsing is robust regardless
+  // of how the model formats its prose. We try, in order: structured output
+  // with a temperature bump (for interactive variety), then structured output
+  // without it (for models that reject a temperature override), then plain text
+  // with delimiter parsing (for models that don't support structured output at
+  // all). Whichever succeeds first wins.
+  progress.onPhase?.(
+    count > 1 ? "Writing commit options" : "Writing commit message",
+  );
+
+  const baseOpts = {
+    model: config.models.final,
+    allowApiKey: config.allowApiKey,
+    ...(abortController ? { abortController } : {}),
+  };
+  const temperature =
+    count > 1 && config.interactiveTemperature != null
+      ? config.interactiveTemperature
+      : undefined;
+
+  const attempts: Array<{ structured: boolean; temperature?: number }> = [];
+  if (temperature != null) attempts.push({ structured: true, temperature });
+  attempts.push({ structured: true });
+  attempts.push({ structured: false });
+
+  let messages: string[] | null = null;
+  let lastError: unknown;
+  for (const attempt of attempts) {
+    try {
+      const result = await runPrompt(
+        buildFinalUser(summaries, count, attempt.structured),
+        {
+          ...baseOpts,
+          system: buildFinalSystem(config, attempt.structured),
+          ...(attempt.structured
+            ? {
+                outputFormat: {
+                  type: "json_schema" as const,
+                  schema: MESSAGES_SCHEMA,
+                },
+              }
+            : {}),
+          ...(attempt.temperature != null
+            ? { temperature: attempt.temperature }
+            : {}),
+          ...(!attempt.structured && progress.onText
+            ? { onText: progress.onText }
+            : {}),
+        },
+      );
+      costUsd += result.costUsd;
+      messages = attempt.structured
+        ? extractMessages(result.structured)
+        : count > 1
+          ? parseOptions(result.text)
+          : [result.text];
+      if (messages && messages.length > 0) break;
+    } catch (err) {
+      lastError = err;
+      // If the run was cancelled, stop retrying: the shared abort signal would
+      // make every remaining attempt fail immediately in the same way.
+      if (abortController?.signal.aborted) break;
+    }
+  }
+
+  const cleaned = (messages ?? [])
+    .map(cleanMessage)
+    .filter((m) => m.length > 0);
+  const deduped = dedupe(cleaned);
+  if (deduped.length === 0) {
+    if (lastError instanceof ClaudeCommitError) throw lastError;
+    throw new ClaudeCommitError("The model did not produce a commit message.");
+  }
+
+  return { messages: deduped, summaries, chunkCount: chunks.length, costUsd };
+}
+
+function dedupe(items: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const item of items) {
+    if (!seen.has(item)) {
+      seen.add(item);
+      out.push(item);
+    }
+  }
+  return out;
+}

package/src/git.ts

@@ -0,0 +1,111 @@
+/**
+ * Git operations, implemented with Bun's shell (`Bun.$`).
+ */
+import { $ } from "bun";
+import { ClaudeCommitError } from "./errors";
+import type { FileChange } from "./types";
+
+/**
+ * A git command failed. Subclasses {@link ClaudeCommitError} so the CLI prints
+ * it as a clean, user-facing error rather than a stack trace.
+ */
+export class GitError extends ClaudeCommitError {
+  override name = "GitError";
+}
+
+/** Run a git command, returning stdout. Throws {@link GitError} on failure. */
+async function git(args: string[]): Promise<string> {
+  let res;
+  try {
+    res = await $`git ${args}`.quiet().nothrow();
+  } catch (err) {
+    // Should not happen with `.nothrow()`, but never let a raw shell error leak.
+    throw new GitError(`Could not run git: ${(err as Error).message}`);
+  }
+  if (res.exitCode !== 0) {
+    const stderr = res.stderr.toString().trim();
+    throw new GitError(
+      stderr || `git ${args.join(" ")} exited with code ${res.exitCode}`,
+    );
+  }
+  return res.stdout.toString();
+}
+
+/** True if the current working directory is inside a git work tree. */
+export async function isGitRepo(): Promise<boolean> {
+  try {
+    const res = await $`git rev-parse --is-inside-work-tree`.quiet().nothrow();
+    return res.exitCode === 0 && res.stdout.toString().trim() === "true";
+  } catch {
+    // git missing or unrunnable — treat as "not a usable repo".
+    return false;
+  }
+}
+
+/** Absolute path to the repository root. */
+export async function getRepoRoot(): Promise<string> {
+  return (await git(["rev-parse", "--show-toplevel"])).trim();
+}
+
+/** The unified diff of staged changes (`git diff --cached`). */
+export async function getStagedDiff(): Promise<string> {
+  return git(["diff", "--cached", "--no-color"]);
+}
+
+/** Parsed list of staged files with their status codes. */
+export async function getStagedFiles(): Promise<FileChange[]> {
+  const out = await git(["diff", "--cached", "--name-status"]);
+  return out
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const parts = line.split("\t");
+      const status = parts[0] ?? "";
+      // For renames/copies (`R100\told\tnew`) the destination is the last field.
+      const path = parts[parts.length - 1] ?? "";
+      return { status, path };
+    });
+}
+
+/** Stage every change in the work tree (`git add -A`). */
+export async function stageAll(): Promise<void> {
+  await git(["add", "-A"]);
+}
+
+/** A short one-line stat summary of staged changes (for display). */
+export async function getStagedStat(): Promise<string> {
+  return (await git(["diff", "--cached", "--stat", "--no-color"])).trimEnd();
+}
+
+/**
+ * Create a commit with the given message. The message is piped to
+ * `git commit -F -` over stdin, so arbitrary content (leading dashes, multiple
+ * lines, special characters) is handled safely — and nothing touches disk, so
+ * there is no temp file to be raced or read by another user.
+ */
+export async function commit(message: string): Promise<void> {
+  let proc;
+  try {
+    // `Bun.spawn` throws synchronously if `git` isn't on PATH.
+    proc = Bun.spawn(["git", "commit", "-F", "-"], {
+      stdin: new TextEncoder().encode(message),
+      // We surface our own confirmation, so discard git's stdout summary rather
+      // than leaving an unread pipe that could (in theory) fill and block.
+      stdout: "ignore",
+      stderr: "pipe",
+    });
+  } catch (err) {
+    throw new GitError(`Could not run git: ${(err as Error).message}`);
+  }
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    throw new GitError(stderr || `git commit exited with code ${exitCode}`);
+  }
+}
+
+/** The current branch name (or `HEAD` when detached). */
+export async function getCurrentBranch(): Promise<string> {
+  return (await git(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+}

package/src/prompts.ts

@@ -0,0 +1,243 @@
+/**
+ * Prompt construction for the two-stage pipeline.
+ *
+ * Stage 1 (summary model): read a diff chunk and describe the change factually.
+ * Stage 2 (final model): turn the summaries into a commit message that obeys the
+ * configured formatting rules (conventional commits, gitmoji, template, body).
+ */
+import type { Config } from "./types";
+
+/** Sentinel separating candidate messages in interactive mode. */
+export const OPTION_DELIMITER = "===OPTION===";
+
+/** A compact gitmoji cheat-sheet to steer the model toward sensible choices. */
+const GITMOJI_GUIDE = [
+  "✨ new feature",
+  "🐛 bug fix",
+  "📝 documentation",
+  "♻️ refactor",
+  "⚡️ performance",
+  "✅ tests",
+  "🔧 configuration / tooling",
+  "🎨 structure / formatting",
+  "🚚 move / rename",
+  "🔥 remove code or files",
+  "⬆️ upgrade dependencies",
+  "👷 CI build system",
+  "🚑️ critical hotfix",
+  "🔒️ security",
+].join(", ");
+
+const CONVENTIONAL_TYPES =
+  "feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert";
+
+/** System prompt for the diff-summarization stage. */
+export function buildSummarySystem(): string {
+  return [
+    "You are an expert software engineer analyzing a git diff in preparation for writing a commit message.",
+    "Summarize the change factually and concisely: which files changed, what was added, removed or modified, and the apparent intent and impact of the change.",
+    "Focus on the substance of the change, not a line-by-line readout.",
+    "Do not write a commit message. Do not include code fences or the raw diff.",
+    "If you are told this is one part of a larger change, summarize only the part you are given.",
+  ].join(" ");
+}
+
+/** User prompt for a single diff chunk in the summarization stage. */
+export function buildSummaryUser(
+  chunk: string,
+  index: number,
+  total: number,
+): string {
+  const preamble =
+    total > 1
+      ? `This is part ${index + 1} of ${total} of a larger diff. Summarize only this part:`
+      : "Summarize the following diff:";
+  return `${preamble}\n\n${chunk}`;
+}
+
+/**
+ * JSON schema for the final stage's structured output: a list of candidate
+ * commit messages. Requesting this makes parsing robust regardless of how the
+ * model chooses to format its prose.
+ */
+export const MESSAGES_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  properties: {
+    messages: {
+      type: "array",
+      description:
+        "The commit message(s), each a complete raw commit message string.",
+      items: { type: "string" },
+    },
+  },
+  required: ["messages"],
+  additionalProperties: false,
+};
+
+/** Pull the message list out of a structured-output object, or return null if malformed. */
+export function extractMessages(structured: unknown): string[] | null {
+  if (
+    structured &&
+    typeof structured === "object" &&
+    Array.isArray((structured as { messages?: unknown }).messages)
+  ) {
+    const messages = (structured as { messages: unknown[] }).messages.filter(
+      (m): m is string => typeof m === "string",
+    );
+    if (messages.length > 0) return messages;
+  }
+  return null;
+}
+
+/**
+ * System prompt for the final commit-message stage, encoding all formatting
+ * rules. When `structured` is true, the model returns its messages as JSON, so
+ * the "no markdown" guidance is scoped to each message's own text.
+ */
+export function buildFinalSystem(config: Config, structured = false): string {
+  const rules: string[] = [
+    "You are an expert at writing clear, high-quality git commit messages.",
+    "You are given a summary of staged changes and must produce a commit message for them.",
+  ];
+
+  // Subject-line style.
+  if (config.conventionalCommits) {
+    rules.push(
+      `Format the subject line as a Conventional Commit: "type(scope): description". ` +
+        `Choose the most appropriate type from: ${CONVENTIONAL_TYPES}. ` +
+        `The scope is optional and should be a short noun for the affected area. ` +
+        `The description is in the imperative mood, lower case, with no trailing period.`,
+    );
+  } else {
+    rules.push(
+      'Write the subject line in the imperative mood (e.g. "Add", not "Added" or "Adds"), ' +
+        "capitalized, concise (aim for 50 characters, 72 at most), with no trailing period.",
+    );
+  }
+
+  if (config.gitmoji) {
+    rules.push(
+      `Begin the subject line with a single appropriate gitmoji, followed by a space. ` +
+        `Pick from: ${GITMOJI_GUIDE}.` +
+        (config.conventionalCommits
+          ? ' Place the gitmoji before the conventional-commit type, e.g. "✨ feat: ...".'
+          : ""),
+    );
+  }
+
+  if (config.template) {
+    rules.push(
+      `The subject line MUST follow this exact template, substituting {message} with the commit description ` +
+        `(after applying the rules above to that description): "${config.template}".`,
+    );
+  }
+
+  if (config.multiline) {
+    rules.push(
+      "After the subject line, add one blank line and then a body that explains what changed and why. " +
+        'Use concise bullet points ("- ...") when there are several distinct changes. Wrap body lines at about 72 characters.',
+    );
+  } else {
+    rules.push("Output only the single subject line. Do not include a body.");
+  }
+
+  if (config.customPrompt) {
+    rules.push(`Additional instructions from the user: ${config.customPrompt}`);
+  }
+
+  rules.push(
+    structured
+      ? "Each commit message must be the raw message text only — no surrounding quotes, no markdown, and no code fences."
+      : "Output ONLY the commit message itself: no surrounding quotes, no markdown, no code fences, no preamble, and no explanation.",
+  );
+
+  return rules.join("\n");
+}
+
+/**
+ * The shared instruction for requesting several distinct options.
+ *
+ * It insists each option be a COMPLETE message obeying the formatting rules —
+ * crucially the body when `multiline` is on. The previous wording asked the
+ * model to "vary the structure" of the options, which let it drop bodies to
+ * manufacture variety, so `multiline` appeared to be ignored in interactive
+ * mode even though the system prompt still required a body.
+ */
+function multiOptionInstruction(count: number): string {
+  return (
+    `Produce exactly ${count} distinct commit-message options for this change. ` +
+    `Each option must be a complete commit message that independently obeys all the formatting rules above — ` +
+    `including the blank line and body when those rules ask for one. ` +
+    `Make the options genuinely different in wording and emphasis, but never drop the subject or a required body just to create variety.`
+  );
+}
+
+/**
+ * User prompt for the final stage.
+ *
+ * In `structured` mode the candidates are returned via {@link MESSAGES_SCHEMA}'s
+ * `messages` array. Otherwise, when `count` > 1, they are separated by
+ * {@link OPTION_DELIMITER} for text parsing.
+ */
+export function buildFinalUser(
+  summaries: string[],
+  count = 1,
+  structured = false,
+): string {
+  const joined =
+    summaries.length === 1
+      ? summaries[0]!
+      : summaries.map((s, i) => `Part ${i + 1}:\n${s}`).join("\n\n");
+
+  const header =
+    summaries.length === 1
+      ? "Here is the summary of the staged changes:"
+      : "Here are summaries of the parts of the staged changes:";
+
+  if (structured) {
+    const ask =
+      count <= 1
+        ? `Produce a single commit message for this change and return it as the only element of the "messages" array.`
+        : `${multiOptionInstruction(count)} Return them in the "messages" array.`;
+    return `${header}\n\n${joined}\n\n${ask}`;
+  }
+
+  if (count <= 1) {
+    return `${header}\n\n${joined}`;
+  }
+
+  return (
+    `${header}\n\n${joined}\n\n${multiOptionInstruction(count)} ` +
+    `Output each option on its own, preceded by a line containing exactly "${OPTION_DELIMITER}" and nothing else. ` +
+    `Do not number the options or add any other text.`
+  );
+}
+
+/** Parse the multi-option response from the final stage into individual messages. */
+export function parseOptions(text: string): string[] {
+  return text
+    .split(OPTION_DELIMITER)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+/** Strip stray formatting a model may add despite instructions (fences, wrapping quotes). */
+export function cleanMessage(text: string): string {
+  let msg = text.trim();
+
+  // Remove a single wrapping fenced code block.
+  const fence = msg.match(/^```[^\n]*\n([\s\S]*?)\n?```$/);
+  if (fence) msg = fence[1]!.trim();
+
+  // Remove matching wrapping quotes only if the whole message is quoted.
+  if (msg.length >= 2) {
+    const first = msg[0];
+    const last = msg[msg.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      const inner = msg.slice(1, -1);
+      if (!inner.includes(first)) msg = inner.trim();
+    }
+  }
+
+  return msg;
+}