@synmux/claude-commit 0.1.0

package/src/tokens.ts

@@ -0,0 +1,20 @@
+/**
+ * Lightweight token estimation.
+ *
+ * We deliberately avoid a real tokenizer here: chunking only needs a rough,
+ * conservative estimate to decide where to split a diff, and pulling in a
+ * tokenizer (or a network round-trip to `count_tokens`) would add weight and
+ * latency for no real benefit. We slightly over-estimate tokens so that chunks
+ * stay safely under the model's context window.
+ */
+
+/** Estimate the number of tokens in `text` given a chars-per-token ratio. */
+export function estimateTokens(text: string, charsPerToken: number): number {
+  if (charsPerToken <= 0) throw new Error("charsPerToken must be positive");
+  return Math.ceil(text.length / charsPerToken);
+}
+
+/** Convert a token budget into an approximate character budget. */
+export function tokensToChars(tokens: number, charsPerToken: number): number {
+  return Math.floor(tokens * charsPerToken);
+}

package/src/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared types for claude-commit.
+ */
+
+/** Which models to use for each stage of the pipeline. */
+export interface ModelConfig {
+  /** Model used to read diffs and write summaries. Defaults to `sonnet[1m]`. */
+  summary: string;
+  /** Model used to turn summaries into the final commit message. Defaults to `haiku`. */
+  final: string;
+}
+
+/** Fully-resolved configuration after merging defaults, file config and CLI flags. */
+export interface Config {
+  /** Format the subject line as a Conventional Commit (`type(scope): description`). */
+  conventionalCommits: boolean;
+  /** Prefix the subject line with a gitmoji. */
+  gitmoji: boolean;
+  /** Produce a multi-line commit (subject + body) instead of a single subject line. */
+  multiline: boolean;
+  /**
+   * Template for the first line. `{message}` is replaced with the generated
+   * subject. Useful for ticket prefixes, e.g. `"[PROJ-123] {message}"`.
+   */
+  template: string | null;
+  /** Extra instructions appended to the standard prompt. */
+  customPrompt: string | null;
+  /**
+   * Default to interactive mode (the `-i` selection TUI) on every run, without
+   * needing to pass `-i`. Override for a single run with `--no-interactive`.
+   * When there is no interactive terminal (a pipe, CI, etc.) this is ignored and
+   * cco falls back to the non-interactive flow rather than failing.
+   */
+  interactive: boolean;
+  /** How many candidate messages to generate in interactive mode. */
+  interactiveCount: number;
+  /**
+   * Sampling temperature for the final model when generating interactive
+   * options, to encourage variety between candidates. `null` leaves the model
+   * at its default. Only applied in interactive mode.
+   */
+  interactiveTemperature: number | null;
+  /** Models for each pipeline stage. */
+  models: ModelConfig;
+  /**
+   * Approximate maximum number of tokens of diff to send to the summary model
+   * in a single request. Diffs larger than this are split across requests.
+   */
+  maxChunkTokens: number;
+  /** Approximate characters-per-token ratio used for chunk-size estimation. */
+  charsPerToken: number;
+  /**
+   * Allow API credentials from the environment (`ANTHROPIC_API_KEY` /
+   * `ANTHROPIC_AUTH_TOKEN`) to be used, billing pay-as-you-go instead of the
+   * Claude subscription. When false (the default) those variables are
+   * stripped from the environment passed to the Claude Agent SDK subprocess,
+   * so an exported key can never silently switch billing.
+   */
+  allowApiKey: boolean;
+}
+
+/** Partial config as it may appear in a config file or be produced by flags. */
+export type PartialConfig = {
+  [K in keyof Config]?: K extends "models" ? Partial<ModelConfig> : Config[K];
+};
+
+/** Result of a single model invocation. */
+export interface ModelResult {
+  /** The text the model produced. */
+  text: string;
+  /** Cost of the call in USD, if reported. */
+  costUsd: number;
+  /** The model that actually served the request, if reported. */
+  model?: string;
+  /** Parsed structured output, when a JSON-schema `outputFormat` was requested. */
+  structured?: unknown;
+}
+
+/** A staged change as seen by `git`. */
+export interface FileChange {
+  /** Status code from `git diff --name-status` (e.g. `A`, `M`, `D`, `R100`). */
+  status: string;
+  /** Path of the file (the destination path for renames). */
+  path: string;
+}

package/src/ui/colors.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal ANSI color helpers for stderr output.
+ *
+ * Color is emitted only when stderr is a TTY and `NO_COLOR` is unset, so escape
+ * codes never leak into redirected logs or CI output.
+ */
+export const useColor = Boolean(process.stderr.isTTY) && !process.env.NO_COLOR;
+
+/** Wrap `text` in an ANSI SGR sequence when color is enabled, else return it unchanged. */
+export function color(code: string, text: string): string {
+  return useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+}

package/src/ui/editor.ts

@@ -0,0 +1,89 @@
+/**
+ * Launching the user's `$EDITOR` to tweak a commit message, plus a tiny
+ * yes/no/edit confirmation prompt for non-interactive runs in a TTY.
+ */
+import { spawn } from "node:child_process";
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createInterface } from "node:readline";
+import { ClaudeCommitError } from "../errors";
+
+/** Resolve the editor command, mirroring git's lookup order. */
+function resolveEditor(): string {
+  return (
+    process.env.GIT_EDITOR || process.env.VISUAL || process.env.EDITOR || "vi"
+  );
+}
+
+/** Open `initial` in the user's editor and return the saved contents. */
+export async function editInEditor(initial: string): Promise<string> {
+  const editor = resolveEditor();
+  // Unpredictable name + exclusive create (`wx`) + owner-only perms (0o600)
+  // so the temp file can't be pre-created as a symlink or read by other users.
+  const file = join(tmpdir(), `claude-commit-edit-${randomUUID()}.txt`);
+  try {
+    await writeFile(file, initial, { mode: 0o600, flag: "wx" });
+  } catch (err) {
+    throw new ClaudeCommitError(
+      `Could not create a temporary file to edit the message: ${(err as Error).message}`,
+    );
+  }
+  try {
+    await runEditor(editor, file);
+    const edited = await readFile(file, "utf8");
+    // Drop trailing whitespace/newline noise editors tend to add.
+    return edited.replace(/\s+$/, "");
+  } catch (err) {
+    if (err instanceof ClaudeCommitError) throw err;
+    throw new ClaudeCommitError(
+      `Editing the commit message failed (${editor}): ${(err as Error).message}`,
+    );
+  } finally {
+    await unlink(file).catch(() => {});
+  }
+}
+
+function runEditor(editor: string, file: string): Promise<void> {
+  return new Promise((resolvePromise, reject) => {
+    // $EDITOR / $GIT_EDITOR are shell command lines that may contain flags,
+    // spaces in the program path, or quoted arguments (e.g. "code --wait" or
+    // "/path/with spaces/editor"). Run them through the shell exactly as git
+    // does rather than naively splitting on whitespace. The file path is our
+    // own (tmpdir + UUID), so double-quoting it is safe.
+    const child = spawn(`${editor} "${file}"`, {
+      stdio: "inherit",
+      shell: true,
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0 || code === null) resolvePromise();
+      else reject(new Error(`Editor exited with code ${code}`));
+    });
+  });
+}
+
+export type ConfirmChoice = "yes" | "no" | "edit";
+
+/** Prompt for [Y]es / [n]o / [e]dit. Requires an interactive stdin. */
+export async function confirmCommit(): Promise<ConfirmChoice> {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    for (;;) {
+      const answer = (
+        await new Promise<string>((res) =>
+          rl.question("Commit this message? [Y/n/e] ", res),
+        )
+      )
+        .trim()
+        .toLowerCase();
+      if (answer === "" || answer === "y" || answer === "yes") return "yes";
+      if (answer === "n" || answer === "no") return "no";
+      if (answer === "e" || answer === "edit") return "edit";
+      process.stderr.write("Please answer y, n, or e.\n");
+    }
+  } finally {
+    rl.close();
+  }
+}

package/src/ui/interactive.ts

@@ -0,0 +1,313 @@
+/**
+ * Interactive mode: generate several candidate messages, then let the user pick
+ * one (and optionally edit it) before committing.
+ *
+ * The picker is an OpenTUI selection screen. All key handling is driven through
+ * the renderer's global key handler so there is a single source of truth for
+ * navigation. If the TUI cannot be initialized for any reason, we transparently
+ * fall back to a plain readline prompt.
+ */
+import { createInterface } from "node:readline";
+import { commit } from "../git";
+import { generateCommit } from "../generate";
+import { Spinner } from "./spinner";
+import { editInEditor } from "./editor";
+import { color } from "./colors";
+import type { Config } from "../types";
+
+export interface InteractiveOptions {
+  verbose: boolean;
+  abortController: AbortController;
+}
+
+type Selection =
+  { action: "commit" | "edit"; index: number } | { action: "cancel" };
+
+/** Run the full interactive flow. Returns a process exit code. */
+export async function runInteractive(
+  diff: string,
+  config: Config,
+  opts: InteractiveOptions,
+): Promise<number> {
+  const count = Math.max(1, config.interactiveCount);
+  const spinner = new Spinner(process.stderr.isTTY);
+  spinner.start(`Generating ${count} option${count === 1 ? "" : "s"}`);
+  let result;
+  try {
+    result = await generateCommit(diff, config, {
+      count,
+      progress: { onPhase: (label) => spinner.update(label) },
+      abortController: opts.abortController,
+    });
+  } catch (err) {
+    spinner.stop();
+    throw err;
+  }
+  spinner.stop();
+
+  const messages = result.messages;
+
+  let selection: Selection;
+  try {
+    selection = await selectWithTui(messages);
+  } catch {
+    // TUI failed to initialize (unusual terminal, etc.) — degrade gracefully.
+    selection = await selectWithReadline(messages);
+  }
+
+  if (selection.action === "cancel") {
+    process.stderr.write("Aborted. Nothing was committed.\n");
+    return 1;
+  }
+
+  let message = messages[selection.index]!;
+  if (selection.action === "edit") {
+    message = await editInEditor(message);
+    if (message.trim() === "") {
+      process.stderr.write("Aborted: empty commit message.\n");
+      return 1;
+    }
+  }
+
+  await commit(message);
+  process.stderr.write(
+    `${color("32", "✔")} Committed\n${color("90", firstLine(message))}\n`,
+  );
+  if (opts.verbose) {
+    process.stderr.write(
+      color("90", `cost $${result.costUsd.toFixed(4)}`) + "\n",
+    );
+  }
+  return 0;
+}
+
+/**
+ * Rows a single candidate occupies in the picker: the subject line plus a
+ * one-line body preview (`showDescription`), with OpenTUI's default
+ * `itemSpacing` of 0. Mirrors SelectRenderable's own line accounting.
+ */
+const PICKER_LINES_PER_ITEM = 2;
+
+/**
+ * Rows reserved for the non-picker chrome when capping its height: root padding
+ * (2), the header line (1) and the gap below it (1).
+ */
+const PICKER_CHROME_ROWS = 4;
+
+/**
+ * The picker's height, sized to its content (two rows per candidate) but capped
+ * to the terminal so a large `interactiveCount` still fits; past the cap the list
+ * scrolls internally (see `showScrollIndicator` in {@link buildPickerScene}). An
+ * explicit height keeps the picker compact — only as tall as the options need —
+ * rather than stretching to fill the screen.
+ */
+export function pickerHeight(count: number, terminalRows: number): number {
+  const wanted = Math.max(1, count) * PICKER_LINES_PER_ITEM;
+  const cap = Math.max(
+    PICKER_LINES_PER_ITEM,
+    terminalRows - PICKER_CHROME_ROWS,
+  );
+  return Math.min(wanted, cap);
+}
+
+/** The `@opentui/core` module, however it is obtained (dynamic import or test). */
+type TuiModule = typeof import("@opentui/core");
+/** The renderer object returned by `createCliRenderer` (and the headless test renderer). */
+type TuiRenderer = Awaited<ReturnType<TuiModule["createCliRenderer"]>>;
+
+/** The renderables the caller wires key handling to after building the scene. */
+export interface PickerScene {
+  root: InstanceType<TuiModule["BoxRenderable"]>;
+  select: InstanceType<TuiModule["SelectRenderable"]>;
+}
+
+/**
+ * Build the picker's renderable tree: a header line above the candidate list.
+ * Extracted from {@link selectWithTui} so the layout can be rendered under
+ * OpenTUI's headless test renderer and asserted on. The caller adds `root` to
+ * the renderer and wires key handling to the returned `select`.
+ */
+export function buildPickerScene(
+  renderer: TuiRenderer,
+  tui: TuiModule,
+  messages: string[],
+  terminalRows: number,
+): PickerScene {
+  const { BoxRenderable, TextRenderable, SelectRenderable } = tui;
+
+  const root = new BoxRenderable(renderer, {
+    flexDirection: "column",
+    width: "100%",
+    height: "100%",
+    padding: 1,
+    gap: 1,
+  });
+
+  const header = new TextRenderable(renderer, {
+    content:
+      "Pick a commit message   ↑/↓ select · ⏎ commit · e edit · q cancel",
+  });
+
+  // A compact, content-sized list of the candidate messages. flexShrink:0 keeps
+  // it at its full height; showScrollIndicator covers more options than fit.
+  const select = new SelectRenderable(renderer, {
+    height: pickerHeight(messages.length, terminalRows),
+    flexShrink: 0,
+    showScrollIndicator: true,
+    options: messages.map((message, index) => ({
+      name: firstLine(message),
+      description: bodyPreview(message),
+      value: index,
+    })),
+    selectedIndex: 0,
+    showDescription: true,
+    wrapSelection: true,
+    // A calm slate highlight (OpenTUI's own default background) with soft
+    // near-white text — the previous bright cyan/black fill was too harsh.
+    // The default description greys (#888888 / #CCCCCC) read fine on the slate,
+    // so they are left untouched.
+    selectedBackgroundColor: "#334455",
+    selectedTextColor: "#e6edf3",
+  });
+
+  root.add(header);
+  root.add(select);
+
+  return { root, select };
+}
+
+/** The OpenTUI selection screen. Resolves with the user's choice. */
+async function selectWithTui(messages: string[]): Promise<Selection> {
+  const tui = await import("@opentui/core");
+  const renderer = await tui.createCliRenderer({ exitOnCtrlC: false });
+
+  return await new Promise<Selection>((resolve, reject) => {
+    let settled = false;
+    let onKey: (key: { name?: string; ctrl?: boolean }) => void = () => {};
+
+    const cleanup = () => {
+      try {
+        renderer.keyInput.off("keypress", onKey);
+      } catch {
+        /* ignore */
+      }
+      try {
+        renderer.destroy();
+      } catch {
+        /* ignore */
+      }
+    };
+    const finish = (sel: Selection) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(sel);
+    };
+
+    try {
+      const terminalRows = process.stdout.rows ?? 24;
+      const { root, select } = buildPickerScene(
+        renderer,
+        tui,
+        messages,
+        terminalRows,
+      );
+      renderer.root.add(root);
+
+      onKey = (key) => {
+        if (!key) return; // some terminals can emit empty/unknown key events
+        try {
+          switch (key.name) {
+            case "up":
+            case "k":
+              select.moveUp();
+              renderer.requestRender();
+              break;
+            case "down":
+            case "j":
+              select.moveDown();
+              renderer.requestRender();
+              break;
+            case "return":
+            case "enter":
+              finish({ action: "commit", index: select.getSelectedIndex() });
+              break;
+            case "e":
+              finish({ action: "edit", index: select.getSelectedIndex() });
+              break;
+            case "q":
+            case "escape":
+              finish({ action: "cancel" });
+              break;
+            case "c":
+              if (key.ctrl) finish({ action: "cancel" });
+              break;
+          }
+        } catch {
+          // A renderable method threw unexpectedly. Rather than let the error
+          // escape the key handler and leave the terminal stuck in raw mode,
+          // cancel cleanly — finish() restores the terminal via cleanup().
+          finish({ action: "cancel" });
+        }
+      };
+
+      renderer.keyInput.on("keypress", onKey);
+      renderer.start();
+      renderer.requestRender();
+    } catch (err) {
+      cleanup();
+      reject(err);
+    }
+  });
+}
+
+/** Plain-prompt fallback when the TUI is unavailable. */
+async function selectWithReadline(messages: string[]): Promise<Selection> {
+  process.stderr.write("\nCandidate commit messages:\n");
+  messages.forEach((m, i) =>
+    process.stderr.write(`  ${i + 1}. ${firstLine(m)}\n`),
+  );
+
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    for (;;) {
+      const answer = (
+        await new Promise<string>((res) =>
+          rl.question(
+            `Choose 1-${messages.length}, "e N" to edit, or q to quit: `,
+            res,
+          ),
+        )
+      )
+        .trim()
+        .toLowerCase();
+
+      if (answer === "q" || answer === "") return { action: "cancel" };
+
+      const editMatch = answer.match(/^e\s*(\d+)$/);
+      if (editMatch) {
+        const index = parseInt(editMatch[1]!, 10) - 1;
+        if (index >= 0 && index < messages.length)
+          return { action: "edit", index };
+      }
+
+      const choice = parseInt(answer, 10);
+      if (choice >= 1 && choice <= messages.length) {
+        return { action: "commit", index: choice - 1 };
+      }
+      process.stderr.write("Invalid choice.\n");
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function firstLine(text: string): string {
+  return text.split("\n", 1)[0] ?? text;
+}
+
+/** A short, single-line preview of a message body (everything after the subject). */
+function bodyPreview(text: string): string {
+  const rest = text.split("\n").slice(1).join(" ").replace(/\s+/g, " ").trim();
+  return rest.length > 120 ? rest.slice(0, 117) + "…" : rest;
+}

package/src/ui/spinner.ts

@@ -0,0 +1,71 @@
+/**
+ * A minimal, dependency-free progress spinner for non-interactive runs.
+ *
+ * It renders to stderr (so stdout stays clean for piping) and only animates when
+ * stderr is a TTY; otherwise `start`/`update` are silent no-ops. This keeps the
+ * read-only progress indicator out of the way of `cco --dry-run | git commit -F -`.
+ */
+import { color } from "./colors";
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const INTERVAL_MS = 80;
+
+export class Spinner {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private frame = 0;
+  private label = "";
+  private readonly enabled: boolean;
+
+  constructor(enabled = process.stderr.isTTY) {
+    this.enabled = Boolean(enabled);
+  }
+
+  start(label: string): void {
+    this.label = label;
+    if (!this.enabled) return;
+    this.stopTimer();
+    process.stderr.write("\x1b[?25l"); // hide cursor
+    this.render();
+    this.timer = setInterval(() => {
+      this.frame = (this.frame + 1) % FRAMES.length;
+      this.render();
+    }, INTERVAL_MS);
+  }
+
+  update(label: string): void {
+    this.label = label;
+    if (this.enabled && this.timer) this.render();
+  }
+
+  /** Stop and clear the spinner line, optionally printing a final status line. */
+  stop(finalLine?: string): void {
+    this.stopTimer();
+    if (this.enabled) {
+      process.stderr.write("\r\x1b[2K\x1b[?25h"); // clear line, show cursor
+    }
+    if (finalLine !== undefined) process.stderr.write(finalLine + "\n");
+  }
+
+  succeed(label: string): void {
+    this.stop(`${color("32", "✔")} ${label}`);
+  }
+
+  fail(label: string): void {
+    this.stop(`${color("31", "✖")} ${label}`);
+  }
+
+  private render(): void {
+    // `\r\x1b[2K` (cursor return + clear line) only runs when enabled (a TTY);
+    // the frame color additionally respects NO_COLOR via the helper.
+    process.stderr.write(
+      `\r\x1b[2K${color("36", FRAMES[this.frame]!)} ${this.label}`,
+    );
+  }
+
+  private stopTimer(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+}