@synmux/claude-commit 0.1.0

package/src/cli.ts

@@ -0,0 +1,315 @@
+/**
+ * Command-line interface: argument parsing (Commander) and orchestration of the
+ * non-interactive and interactive flows.
+ */
+import { Command } from "commander";
+import {
+  commit,
+  getStagedDiff,
+  getStagedStat,
+  isGitRepo,
+  getRepoRoot,
+  stageAll,
+} from "./git";
+import { presentCredentialVars } from "./agent";
+import { loadFileConfig, resolveConfig } from "./config";
+import { generateCommit } from "./generate";
+import { Spinner } from "./ui/spinner";
+import { confirmCommit, editInEditor } from "./ui/editor";
+import { color } from "./ui/colors";
+import { ClaudeCommitError } from "./errors";
+import type { ModelConfig, PartialConfig } from "./types";
+
+export const VERSION = "0.1.0";
+
+interface CliOptions {
+  interactive?: boolean;
+  count?: number;
+  multiline?: boolean;
+  conventional?: boolean;
+  gitmoji?: boolean;
+  template?: string;
+  prompt?: string;
+  all?: boolean;
+  modelSummary?: string;
+  modelFinal?: string;
+  dryRun?: boolean;
+  yes?: boolean;
+  spinner?: boolean;
+  config?: string;
+  verbose?: boolean;
+}
+
+function buildProgram(): Command {
+  const program = new Command();
+  program
+    .name("cco")
+    .description("Generate a git commit message with Claude.")
+    .version(VERSION, "-V, --version", "output the version number")
+    .option(
+      "-i, --interactive",
+      "choose between several options in an interactive TUI",
+    )
+    .option(
+      "--no-interactive",
+      'skip the interactive TUI even when "interactive" is set in config',
+    )
+    .option(
+      "-n, --count <n>",
+      "number of options to generate in interactive mode",
+      (v) => parseInt(v, 10),
+    )
+    .option("-a, --all", "stage all changes (git add -A) before committing")
+    .option("-c, --conventional", "format as a Conventional Commit")
+    .option("-g, --gitmoji", "prefix the subject with a gitmoji")
+    .option("-m, --multiline", "write a multi-line commit (subject + body)")
+    .option("--no-multiline", "write only a single-line subject")
+    .option(
+      "-t, --template <tpl>",
+      'template for the first line, e.g. "[PROJ-1] {message}"',
+    )
+    .option("-p, --prompt <text>", "extra instructions appended to the prompt")
+    .option("--model-summary <model>", "model used to summarize the diff")
+    .option("--model-final <model>", "model used to write the final message")
+    .option("-d, --dry-run", "print the message to stdout without committing")
+    .option("-y, --yes", "commit without asking for confirmation")
+    .option("--no-spinner", "disable the progress spinner")
+    .option("--config <path>", "path to a config file")
+    .option("-v, --verbose", "print summaries, cost and debug output")
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Authentication:",
+        "  Uses the Claude Agent SDK with your Claude Code subscription (run",
+        "  `claude login`). ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN are ignored",
+        '  unless the config sets "allowApiKey": true (pay-as-you-go billing).',
+        "",
+        "Examples:",
+        "  cco                     generate and commit a message for staged changes",
+        "  cco -a -c               stage everything and write a Conventional Commit",
+        "  cco -i                  pick from several options interactively",
+        "  cco --dry-run | cat     print a message without committing",
+      ].join("\n"),
+    );
+  return program;
+}
+
+/** Map parsed CLI flags onto a partial config (only set keys the user provided). */
+function flagsToConfig(opts: CliOptions): PartialConfig {
+  const cfg: PartialConfig = {};
+  if (opts.conventional !== undefined)
+    cfg.conventionalCommits = opts.conventional;
+  if (opts.gitmoji !== undefined) cfg.gitmoji = opts.gitmoji;
+  if (opts.multiline !== undefined) cfg.multiline = opts.multiline;
+  if (opts.interactive !== undefined) cfg.interactive = opts.interactive;
+  if (opts.template !== undefined) cfg.template = opts.template;
+  if (opts.prompt !== undefined) cfg.customPrompt = opts.prompt;
+  if (opts.count !== undefined && Number.isFinite(opts.count)) {
+    cfg.interactiveCount = Math.max(1, opts.count);
+  }
+  const models: Partial<ModelConfig> = {};
+  if (opts.modelSummary) models.summary = opts.modelSummary;
+  if (opts.modelFinal) models.final = opts.modelFinal;
+  if (Object.keys(models).length) cfg.models = models;
+  return cfg;
+}
+
+/**
+ * Decide which flow to run from the resolved config, the raw `--interactive`
+ * flag state, and whether we have an interactive terminal.
+ *
+ * - `--dry-run` always wins: it prints and never commits, so the TUI is skipped.
+ * - Interactive requires a TTY. An explicit `-i` without one is a hard error
+ *   (the user asked for something we cannot provide), whereas interactive coming
+ *   only from config silently falls back to the non-interactive flow so pipes
+ *   and CI keep working.
+ */
+export function resolveInteractiveMode(args: {
+  configInteractive: boolean;
+  interactiveFlag: boolean | undefined;
+  dryRun: boolean;
+  hasTty: boolean;
+}): "interactive" | "non-interactive" | "no-tty-error" {
+  if (args.dryRun) return "non-interactive";
+  if (!args.configInteractive) return "non-interactive";
+  if (args.hasTty) return "interactive";
+  return args.interactiveFlag === true ? "no-tty-error" : "non-interactive";
+}
+
+function printMessage(message: string): void {
+  const bar = color("90", "─".repeat(48));
+  process.stderr.write(`\n${bar}\n${message}\n${bar}\n`);
+}
+
+/** Entry point. Returns a process exit code. */
+export async function run(argv: string[]): Promise<number> {
+  const program = buildProgram();
+  program.parse(argv, { from: "user" });
+  const opts = program.opts<CliOptions>();
+  const verbose = Boolean(opts.verbose);
+
+  const abortController = new AbortController();
+  // Two-stage Ctrl-C: the first interrupt asks the in-flight generation to
+  // cancel gracefully (aborting the SDK subprocess); a second, impatient
+  // interrupt force-quits in case that abort is slow to take effect.
+  let interrupting = false;
+  const onSigint = () => {
+    if (interrupting) {
+      // Second Ctrl-C: force-quit. Restore the cursor in case a spinner hid it,
+      // since this path bypasses the spinner's own cleanup.
+      if (process.stderr.isTTY) process.stderr.write("\x1b[?25h");
+      process.exit(130);
+    }
+    interrupting = true;
+    abortController.abort();
+  };
+  process.on("SIGINT", onSigint);
+
+  try {
+    if (!(await isGitRepo())) {
+      throw new ClaudeCommitError(
+        "Not a git repository (or any parent). Run `cco` inside a repo.",
+      );
+    }
+    const repoRoot = await getRepoRoot();
+    const fileConfig = await loadFileConfig(
+      process.cwd(),
+      repoRoot,
+      opts.config,
+    );
+    const config = resolveConfig(fileConfig, flagsToConfig(opts));
+
+    // Surface the credential gate: the actual stripping happens in the agent
+    // layer, but silently ignoring an exported key would be confusing.
+    if (!config.allowApiKey) {
+      const ignored = presentCredentialVars(process.env);
+      if (ignored.length > 0) {
+        process.stderr.write(
+          color(
+            "90",
+            `Ignoring ${ignored.join(" and ")}: using subscription auth. Set ` +
+              `"allowApiKey": true in your claude-commit config to use API credentials.`,
+          ) + "\n",
+        );
+      }
+    }
+
+    if (opts.all) await stageAll();
+
+    const diff = await getStagedDiff();
+    if (diff.trim() === "") {
+      throw new ClaudeCommitError(
+        opts.all
+          ? "No changes to commit: the working tree is clean."
+          : "No staged changes. Stage files with `git add`, or pass -a/--all to stage everything.",
+      );
+    }
+
+    const interactiveMode = resolveInteractiveMode({
+      configInteractive: config.interactive,
+      interactiveFlag: opts.interactive,
+      dryRun: Boolean(opts.dryRun),
+      hasTty: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    });
+    if (interactiveMode === "no-tty-error") {
+      throw new ClaudeCommitError(
+        "Interactive mode (-i) requires an interactive terminal.",
+      );
+    }
+    if (interactiveMode === "interactive") {
+      const { runInteractive } = await import("./ui/interactive");
+      return await runInteractive(diff, config, { verbose, abortController });
+    }
+
+    return await runNonInteractive(
+      diff,
+      config,
+      opts,
+      verbose,
+      abortController,
+    );
+  } catch (err) {
+    if (err instanceof ClaudeCommitError) {
+      process.stderr.write(`${color("31", "error:")} ${err.message}\n`);
+      return 1;
+    }
+    throw err;
+  } finally {
+    process.off("SIGINT", onSigint);
+  }
+}
+
+async function runNonInteractive(
+  diff: string,
+  config: ReturnType<typeof resolveConfig>,
+  opts: CliOptions,
+  verbose: boolean,
+  abortController: AbortController,
+): Promise<number> {
+  const useSpinner = opts.spinner !== false && process.stderr.isTTY;
+  const spinner = new Spinner(useSpinner);
+
+  spinner.start("Reading diff");
+  let result;
+  try {
+    result = await generateCommit(diff, config, {
+      progress: { onPhase: (label) => spinner.update(label) },
+      abortController,
+    });
+  } catch (err) {
+    spinner.stop(); // always restore the cursor / clear the line on failure
+    throw err;
+  }
+  spinner.stop();
+
+  if (verbose) {
+    process.stderr.write(
+      color(
+        "90",
+        `${result.chunkCount} chunk(s), cost $${result.costUsd.toFixed(4)}`,
+      ) + "\n",
+    );
+    for (const [i, summary] of result.summaries.entries()) {
+      process.stderr.write(
+        color("90", `--- summary ${i + 1} ---\n${summary}`) + "\n",
+      );
+    }
+  }
+
+  let message = result.messages[0]!;
+
+  // Dry run: emit to stdout so it can be piped, and never commit.
+  if (opts.dryRun) {
+    process.stdout.write(message + "\n");
+    return 0;
+  }
+
+  const canPrompt = process.stdin.isTTY && process.stdout.isTTY;
+  if (!opts.yes && canPrompt) {
+    printMessage(message);
+    const choice = await confirmCommit();
+    if (choice === "no") {
+      process.stderr.write("Aborted. Nothing was committed.\n");
+      return 1;
+    }
+    if (choice === "edit") {
+      message = await editInEditor(message);
+      if (message.trim() === "") {
+        process.stderr.write("Aborted: empty commit message.\n");
+        return 1;
+      }
+    }
+  }
+
+  const stat = verbose ? await getStagedStat().catch(() => "") : "";
+  await commit(message);
+  spinner.succeed("Committed");
+  process.stderr.write(color("90", firstLine(message)) + "\n");
+  if (stat) process.stderr.write(color("90", stat) + "\n");
+  return 0;
+}
+
+function firstLine(text: string): string {
+  return text.split("\n", 1)[0] ?? text;
+}

package/src/config.ts

@@ -0,0 +1,247 @@
+/**
+ * Configuration loading and merging.
+ *
+ * Precedence (low to high): built-in defaults < a global user config in
+ * `$XDG_CONFIG_HOME/claude-commit` (default `~/.config/claude-commit`) <
+ * `package.json` (`claude-commit` key at the repo root) < the nearest project
+ * `.claude-commit.json` / `.claude-commitrc(.json)` file (searched cwd → repo
+ * root) < CLI flags.
+ */
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { ClaudeCommitError } from "./errors";
+import type { Config, ModelConfig, PartialConfig } from "./types";
+
+export const DEFAULT_CONFIG: Config = {
+  conventionalCommits: false,
+  gitmoji: false,
+  multiline: false,
+  template: null,
+  customPrompt: null,
+  interactive: false,
+  interactiveCount: 3,
+  interactiveTemperature: 1,
+  models: {
+    summary: "sonnet[1m]",
+    final: "haiku",
+  },
+  maxChunkTokens: 600_000,
+  charsPerToken: 3.5,
+  allowApiKey: false,
+};
+
+const CONFIG_FILENAMES = [
+  ".claude-commit.json",
+  ".claude-commitrc.json",
+  ".claude-commitrc",
+];
+
+/**
+ * Filenames accepted inside the global config directory, most-preferred first.
+ * `config.json` is the canonical name (the directory already says which tool it
+ * is for); the project-style names are also honoured so a config can be copied
+ * or symlinked there.
+ */
+const GLOBAL_CONFIG_FILENAMES = ["config.json", ...CONFIG_FILENAMES];
+
+/**
+ * The user-level config directory, `$XDG_CONFIG_HOME/claude-commit` (falling back
+ * to `~/.config/claude-commit`). Per the XDG Base Directory spec, `XDG_CONFIG_HOME`
+ * is honoured only when it is set to an absolute path.
+ */
+export function globalConfigDir(
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const xdg = env.XDG_CONFIG_HOME;
+  const base = xdg && isAbsolute(xdg) ? xdg : join(homedir(), ".config");
+  return join(base, "claude-commit");
+}
+
+/** The first existing global config file in {@link globalConfigDir}, if any. */
+async function findGlobalConfigFile(
+  env: Record<string, string | undefined> = process.env,
+): Promise<string | undefined> {
+  const dir = globalConfigDir(env);
+  for (const name of GLOBAL_CONFIG_FILENAMES) {
+    const candidate = join(dir, name);
+    if (await Bun.file(candidate).exists()) return candidate;
+  }
+  return undefined;
+}
+
+/** Deep-ish merge of a partial config over a base config (only `models` is nested). */
+export function mergeConfig(base: Config, override: PartialConfig): Config {
+  const models: ModelConfig = { ...base.models, ...(override.models ?? {}) };
+  const merged: Config = { ...base, ...override, models };
+  return merged;
+}
+
+/** Validate and normalize a parsed partial config, ignoring unknown keys. */
+export function sanitizePartial(raw: unknown): PartialConfig {
+  if (raw === null || typeof raw !== "object") return {};
+  const obj = raw as Record<string, unknown>;
+  const out: PartialConfig = {};
+
+  const bool = (k: keyof Config) => {
+    if (typeof obj[k] === "boolean")
+      (out as Record<string, unknown>)[k] = obj[k];
+  };
+  bool("conventionalCommits");
+  bool("gitmoji");
+  bool("multiline");
+  bool("interactive");
+  bool("allowApiKey");
+
+  if (typeof obj.template === "string") out.template = obj.template;
+  else if (obj.template === null) out.template = null;
+  if (typeof obj.customPrompt === "string") out.customPrompt = obj.customPrompt;
+  else if (obj.customPrompt === null) out.customPrompt = null;
+
+  if (
+    typeof obj.interactiveCount === "number" &&
+    Number.isFinite(obj.interactiveCount)
+  ) {
+    out.interactiveCount = Math.max(1, Math.floor(obj.interactiveCount));
+  }
+  if (obj.interactiveTemperature === null) {
+    out.interactiveTemperature = null;
+  } else if (
+    typeof obj.interactiveTemperature === "number" &&
+    Number.isFinite(obj.interactiveTemperature)
+  ) {
+    out.interactiveTemperature = Math.min(
+      2,
+      Math.max(0, obj.interactiveTemperature),
+    );
+  }
+  if (typeof obj.maxChunkTokens === "number" && obj.maxChunkTokens > 0) {
+    out.maxChunkTokens = Math.floor(obj.maxChunkTokens);
+  }
+  if (typeof obj.charsPerToken === "number" && obj.charsPerToken > 0) {
+    out.charsPerToken = obj.charsPerToken;
+  }
+
+  if (obj.models && typeof obj.models === "object") {
+    const m = obj.models as Record<string, unknown>;
+    const models: Partial<ModelConfig> = {};
+    if (typeof m.summary === "string") models.summary = m.summary;
+    if (typeof m.final === "string") models.final = m.final;
+    if (Object.keys(models).length) out.models = models;
+  }
+
+  return out;
+}
+
+async function readJsonIfExists(path: string): Promise<unknown | undefined> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) return undefined;
+  try {
+    return await file.json();
+  } catch (err) {
+    throw new ClaudeCommitError(
+      `Failed to parse config file ${path}: ${(err as Error).message}`,
+    );
+  }
+}
+
+/** Walk from `startDir` up to and including `rootDir`, returning the first config file found. */
+async function findConfigFile(
+  startDir: string,
+  rootDir: string,
+): Promise<string | undefined> {
+  let dir = resolve(startDir);
+  const stop = resolve(rootDir);
+  // Always terminates: we stop at `rootDir`, and `dirname` of the filesystem
+  // root returns itself (`parent === dir`), so even when `startDir` is not under
+  // `rootDir` the walk halts at the root regardless of directory depth.
+  for (;;) {
+    for (const name of CONFIG_FILENAMES) {
+      const candidate = join(dir, name);
+      if (await Bun.file(candidate).exists()) return candidate;
+    }
+    if (dir === stop) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+/**
+ * Load and merge the file-based configuration layers that sit below CLI flags,
+ * lowest first: the global user config, then `package.json`'s `claude-commit` key
+ * at the repo root, then the nearest project config file (searched from `cwd` up
+ * to `repoRoot`). An explicit `configPath` short-circuits the project-file
+ * discovery; the global and `package.json` layers still apply beneath it. `env`
+ * supplies `XDG_CONFIG_HOME` for locating the global config (defaults to
+ * `process.env`).
+ */
+export async function loadFileConfig(
+  cwd: string,
+  repoRoot: string,
+  configPath?: string,
+  env: Record<string, string | undefined> = process.env,
+): Promise<PartialConfig> {
+  let result: PartialConfig = {};
+
+  // Global user config (lowest precedence): $XDG_CONFIG_HOME/claude-commit. Like
+  // a project config file, a malformed one throws (it is a file the user wrote
+  // deliberately), which readJsonIfExists handles.
+  const globalPath = await findGlobalConfigFile(env);
+  if (globalPath) {
+    result = mergePartial(
+      result,
+      sanitizePartial(await readJsonIfExists(globalPath)),
+    );
+  }
+
+  // package.json#claude-commit at the repo root (above the global config, below
+  // project config files). A malformed package.json is not cco's concern to
+  // enforce — skip it rather than blocking the commit (the user may even be
+  // committing its fix).
+  let pkg: unknown;
+  try {
+    pkg = await readJsonIfExists(join(repoRoot, "package.json"));
+  } catch {
+    pkg = undefined;
+  }
+  if (pkg && typeof pkg === "object" && "claude-commit" in (pkg as object)) {
+    result = mergePartial(
+      result,
+      sanitizePartial((pkg as Record<string, unknown>)["claude-commit"]),
+    );
+  }
+
+  const filePath = configPath
+    ? resolve(cwd, configPath)
+    : await findConfigFile(cwd, repoRoot);
+  if (filePath) {
+    const raw = await readJsonIfExists(filePath);
+    if (raw === undefined && configPath) {
+      throw new ClaudeCommitError(`Config file not found: ${filePath}`);
+    }
+    result = mergePartial(result, sanitizePartial(raw));
+  }
+
+  return result;
+}
+
+/** Merge two partial configs (only `models` is nested). */
+export function mergePartial(
+  base: PartialConfig,
+  override: PartialConfig,
+): PartialConfig {
+  const out: PartialConfig = { ...base, ...override };
+  if (base.models || override.models) {
+    out.models = { ...base.models, ...override.models };
+  }
+  return out;
+}
+
+/** Produce a fully-resolved config from file config and CLI-flag overrides. */
+export function resolveConfig(
+  fileConfig: PartialConfig,
+  flagConfig: PartialConfig,
+): Config {
+  return mergeConfig(DEFAULT_CONFIG, mergePartial(fileConfig, flagConfig));
+}