@kud/ai-conventional-commit-cli 0.2.1 → 0.4.0

package/dist/index.js

@@ -4,7 +4,7 @@
 import { Cli, Command, Option } from "clipanion";
 
 // src/workflow/generate.ts
-import chalk from "chalk";
+import chalk2 from "chalk";
 import ora from "ora";
 
 // src/git.ts
@@ -89,6 +89,17 @@ var createCommit = async (title, body) => {
     await git.commit(title);
   }
 };
+var resetIndex = async () => {
+  await git.reset(["--mixed"]);
+};
+var stageFiles = async (files) => {
+  if (!files.length) return;
+  await git.add(files);
+};
+var getStagedFiles = async () => {
+  const status = await git.status();
+  return status.staged;
+};
 
 // src/style.ts
 var buildStyleProfile = (messages) => {
@@ -171,7 +182,7 @@ var buildGenerationMessages = (opts) => {
   );
   specLines.push("Locale: en");
   specLines.push(
-    'Output JSON Schema: { "commits": [ { "title": string, "body": string, "score": 0-100, "reasons": string[] } ], "meta": { "splitRecommended": boolean } }'
+    'Output JSON Schema: { "commits": [ { "title": string, "body": string, "score": 0-100, "reasons": string[], "files"?: string[] } ], "meta": { "splitRecommended": boolean } }'
   );
   specLines.push("Primary Output Field: commits[ ].title");
   specLines.push("Title Format: <type>(<optional-scope>): <subject>");
@@ -196,7 +207,7 @@ var buildGenerationMessages = (opts) => {
     "Provide reasons array citing concrete diff elements: filenames, functions, tests, metrics."
   );
   specLines.push(
-    `Reasoning Depth: ${config.reasoning || "low"} (low=minimal concise reasons, medium=balanced detail, high=very detailed). Adjust reasons verbosity accordingly.`
+    'When mode is split, WHERE POSSIBLE add a "files" array per commit listing the most relevant changed file paths (1-6, minimize overlap across commits).'
   );
   specLines.push("Return ONLY the JSON object. No surrounding text or markdown.");
   specLines.push("Do not add fields not listed in schema.");
@@ -352,7 +363,8 @@ var CommitSchema = z.object({
   title: z.string().min(5).max(150),
   body: z.string().optional().default(""),
   score: z.number().min(0).max(100),
-  reasons: z.array(z.string()).optional().default([])
+  reasons: z.array(z.string()).optional().default([]),
+  files: z.array(z.string()).optional().default([])
 });
 var PlanSchema = z.object({
   commits: z.array(CommitSchema).min(1),
@@ -547,7 +559,149 @@ var formatCommitTitle = (raw, opts) => {
 import { writeFileSync, mkdirSync, existsSync } from "fs";
 import { join } from "path";
 import inquirer from "inquirer";
+
+// src/workflow/ui.ts
+import chalk from "chalk";
+function animateHeaderBase(text = "ai-conventional-commit") {
+  if (!process.stdout.isTTY || process.env.AICC_NO_ANIMATION) {
+    console.log("\n\u250C " + chalk.bold(text));
+    return Promise.resolve();
+  }
+  const palette = [
+    "#3a0d6d",
+    "#5a1ea3",
+    "#7a32d6",
+    "#9a4dff",
+    "#b267ff",
+    "#c37dff",
+    "#b267ff",
+    "#9a4dff",
+    "#7a32d6",
+    "#5a1ea3"
+  ];
+  process.stdout.write("\n");
+  return palette.reduce(async (p, color) => {
+    await p;
+    const frame = chalk.bold.hex(color)(text);
+    process.stdout.write("\r\u250C " + frame);
+    await new Promise((r) => setTimeout(r, 60));
+  }, Promise.resolve()).then(() => process.stdout.write("\n"));
+}
+function borderLine(content) {
+  if (!content) console.log("\u2502");
+  else console.log("\u2502 " + content);
+}
+function sectionTitle(label) {
+  console.log("\u2299 " + chalk.bold(label));
+}
+function abortMessage() {
+  console.log("\u2514 \u{1F645}\u200D\u2640\uFE0F No commit created.");
+}
+function finalSuccess(opts) {
+  const elapsedMs = Date.now() - opts.startedAt;
+  const seconds = elapsedMs / 1e3;
+  const dur = seconds >= 0.1 ? seconds.toFixed(1) + "s" : elapsedMs + "ms";
+  const plural = opts.count !== 1;
+  if (plural) console.log(`\u2514 \u2728 ${opts.count} commits created in ${dur}.`);
+  else console.log(`\u2514 \u2728 commit created in ${dur}.`);
+}
+function createPhasedSpinner(oraLib) {
+  const useAnim = process.stdout.isTTY && !process.env.AICC_NO_ANIMATION && !process.env.AICC_NO_SPINNER_ANIM;
+  const palette = [
+    "#3a0d6d",
+    "#5a1ea3",
+    "#7a32d6",
+    "#9a4dff",
+    "#b267ff",
+    "#c37dff",
+    "#b267ff",
+    "#9a4dff",
+    "#7a32d6",
+    "#5a1ea3"
+  ];
+  let label = "Starting";
+  let i = 0;
+  const spinner = oraLib({ text: chalk.bold(label), spinner: "dots" }).start();
+  let interval = null;
+  function frame() {
+    if (!useAnim) return;
+    spinner.text = chalk.bold.hex(palette[i])(label);
+    i = (i + 1) % palette.length;
+  }
+  if (useAnim) {
+    frame();
+    interval = setInterval(frame, 80);
+  }
+  function setLabel(next) {
+    label = next;
+    if (useAnim) {
+      i = 0;
+      frame();
+    } else {
+      spinner.text = chalk.bold(label);
+    }
+  }
+  function stopAnim() {
+    if (interval) {
+      clearInterval(interval);
+      interval = null;
+    }
+  }
+  return {
+    spinner,
+    async step(l, fn) {
+      setLabel(l);
+      try {
+        return await fn();
+      } catch (e) {
+        stopAnim();
+        const msg = `${l} failed: ${e?.message || e}`.replace(/^\s+/, "");
+        spinner.fail(msg);
+        throw e;
+      }
+    },
+    phase(l) {
+      setLabel(l);
+    },
+    stop() {
+      stopAnim();
+      spinner.stop();
+    }
+  };
+}
+function renderCommitBlock(opts) {
+  const dim = (s) => chalk.dim(s);
+  const white = (s) => chalk.white(s);
+  const msgColor = opts.messageLabelColor || dim;
+  const descColor = opts.descriptionLabelColor || dim;
+  const titleColor = opts.titleColor || white;
+  const bodyFirst = opts.bodyFirstLineColor || white;
+  const bodyRest = opts.bodyLineColor || white;
+  if (opts.fancy) {
+    const heading = opts.heading ? chalk.hex("#9a4dff").bold(opts.heading) : void 0;
+    if (heading) borderLine(heading);
+    borderLine(msgColor("Title:") + " " + titleColor(`${opts.indexPrefix || ""}${opts.title}`));
+  } else {
+    if (opts.heading) borderLine(chalk.bold(opts.heading));
+    if (!opts.hideMessageLabel)
+      borderLine(msgColor("Message:") + " " + titleColor(`${opts.indexPrefix || ""}${opts.title}`));
+    else
+      borderLine(msgColor("Title:") + " " + titleColor(`${opts.indexPrefix || ""}${opts.title}`));
+  }
+  borderLine();
+  if (opts.body) {
+    const lines = opts.body.split("\n");
+    lines.forEach((line, i) => {
+      if (line.trim().length === 0) borderLine();
+      else if (i === 0) borderLine(descColor("Description:") + " " + bodyFirst(line));
+      else borderLine(bodyRest(line));
+    });
+  }
+}
+
+// src/workflow/generate.ts
 async function runGenerate(config) {
+  const startedAt = Date.now();
   if (!await ensureStagedChanges()) {
     console.log("No staged changes.");
     return;
@@ -557,24 +711,18 @@ async function runGenerate(config) {
     console.log("No diff content detected after staging. Aborting.");
     return;
   }
-  console.log("\n\u250C  " + chalk.bold("ai-conventional-commit"));
-  console.log("\u2502");
-  console.log(`\u25C6  ${chalk.bold(`Detected ${files.length} staged files:`)}`);
-  for (const f of files) console.log("   " + f.file);
-  console.log("\u2502");
-  const spinner = ora({ text: " Starting", spinner: "dots" }).start();
-  function setPhase(label) {
-    spinner.text = " " + chalk.bold(label);
-  }
-  async function runStep(label, fn) {
-    setPhase(label);
-    try {
-      return await fn();
-    } catch (e) {
-      spinner.fail(`\u25C7  ${label} failed: ${e.message}`);
-      throw e;
-    }
+  if (process.stdout.isTTY) {
+    await animateHeaderBase();
+    borderLine();
   }
+  sectionTitle("Files");
+  borderLine(
+    chalk2.dim(`Detected ${files.length} staged ${files.length === 1 ? "file" : "files"}:`)
+  );
+  files.forEach((f) => borderLine("\u2022 " + f.file));
+  borderLine();
+  const phased = createPhasedSpinner(ora);
+  const runStep = (label, fn) => phased.step(label, fn);
   let style;
   let plugins;
   let messages;
@@ -600,8 +748,9 @@ async function runGenerate(config) {
     "Analyzing changes",
     async () => applyTransforms(plan.commits, plugins, { cwd: process.cwd(), env: process.env })
   );
-  setPhase("Result found");
-  spinner.stopAndPersist({ symbol: "\u25C6", text: " " + chalk.bold("Result found:") });
+  phased.phase("Suggested commit");
+  phased.stop();
+  sectionTitle("Suggested commit");
   candidates = candidates.map((c) => ({
     ...c,
     title: formatCommitTitle(c.title, {
@@ -610,15 +759,7 @@ async function runGenerate(config) {
     })
   }));
   const chosen = candidates[0];
-  console.log("   " + chalk.yellow(chosen.title));
-  if (chosen.body) {
-    const indent = "   ";
-    chosen.body.split("\n").forEach((line) => {
-      if (line.trim().length === 0) console.log(indent);
-      else console.log(indent + chalk.gray(line));
-    });
-  }
-  console.log("\u2502");
+  renderCommitBlock({ title: chosen.title, body: chosen.body });
   const pluginErrors = await runValidations(chosen, plugins, {
     cwd: process.cwd(),
     env: process.env
@@ -626,18 +767,22 @@ async function runGenerate(config) {
   const guardErrors = checkCandidate(chosen);
   const errors = [...pluginErrors, ...guardErrors];
   if (errors.length) {
-    console.log(chalk.red("! Validation issues:"));
-    errors.forEach((e) => console.log("  -", e));
-    console.log("\u2502");
+    borderLine();
+    console.log("\u2299 " + chalk2.bold("Checks"));
+    const errorLines = ["Validation issues:", ...errors.map((e) => chalk2.red("\u2022 " + e))];
+    errorLines.forEach((l) => borderLine(l));
   }
+  borderLine();
   const yn = await selectYesNo();
   if (!yn) {
-    console.log("Aborted.");
+    borderLine();
+    abortMessage();
     return;
   }
   await createCommit(chosen.title, chosen.body);
   saveSession({ plan, chosen, mode: "single" });
-  console.log(chalk.green("Commit created."));
+  borderLine();
+  finalSuccess({ count: 1, startedAt });
 }
 function saveSession(data) {
   const dir = ".git/.aicc-cache";
@@ -649,10 +794,10 @@ async function selectYesNo() {
     {
       type: "list",
       name: "choice",
-      message: " Use this commit message?",
+      message: "Use the commit?",
       choices: [
-        { name: "\u25CF Yes", value: true },
-        { name: "\u25CB No", value: false }
+        { name: "Yes", value: true },
+        { name: "No", value: false }
       ],
       default: 0
     }
@@ -661,7 +806,8 @@ async function selectYesNo() {
 }
 
 // src/workflow/split.ts
-import chalk2 from "chalk";
+import chalk3 from "chalk";
+import ora2 from "ora";
 
 // src/cluster.ts
 var topLevel = (file) => file.split("/")[0] || file;
@@ -707,6 +853,7 @@ import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync as
 import { join as join2 } from "path";
 import inquirer2 from "inquirer";
 async function runSplit(config, desired) {
+  const startedAt = Date.now();
   if (!await ensureStagedChanges()) {
     console.log("No staged changes.");
     return;
@@ -716,43 +863,45 @@ async function runSplit(config, desired) {
     console.log("No diff content detected after staging. Aborting.");
     return;
   }
-  console.log("\u25C7  Clustering changes");
-  clusterHunks(files);
-  console.log("\u25C7  Profiling style");
-  const history = await getRecentCommitMessages(config.styleSamples);
-  const style = buildStyleProfile(history);
-  console.log("\u25C7  Loading plugins");
-  const plugins = await loadPlugins(config);
-  console.log("\u25C7  Building prompt");
-  const messages = buildGenerationMessages({
-    files,
-    style,
-    config,
-    mode: "split",
-    desiredCommits: desired
-  });
-  const provider = new OpenCodeProvider(config.model);
-  console.log("\u25C7  Calling model for split plan");
-  let raw;
-  try {
-    raw = await provider.chat(messages, { maxTokens: config.maxTokens });
-  } catch (e) {
-    console.log(e.message);
-    return;
-  }
-  console.log("\u25C7  Parsing response");
-  let plan;
-  try {
-    plan = extractJSON(raw);
-  } catch (e) {
-    console.log("JSON parse error: " + e.message);
-    return;
+  if (process.stdout.isTTY) {
+    await animateHeaderBase();
+    borderLine();
   }
-  console.log("\u25C7  Plan received");
-  let candidates = await applyTransforms(plan.commits, plugins, {
-    cwd: process.cwd(),
-    env: process.env
+  sectionTitle("Files");
+  borderLine(
+    chalk3.dim(`Detected ${files.length} staged ${files.length === 1 ? "file" : "files"}:`)
+  );
+  files.forEach((f) => borderLine("\u2022 " + f.file));
+  borderLine();
+  const phased = createPhasedSpinner(ora2);
+  const runStep = (label, fn) => phased.step(label, fn);
+  await runStep("Clustering changes", async () => {
+    clusterHunks(files);
   });
+  const style = await runStep("Profiling style", async () => {
+    const history = await getRecentCommitMessages(config.styleSamples);
+    return buildStyleProfile(history);
+  });
+  const plugins = await runStep("Loading plugins", async () => loadPlugins(config));
+  const messages = await runStep(
+    "Building prompt",
+    async () => buildGenerationMessages({ files, style, config, mode: "split", desiredCommits: desired })
+  );
+  const provider = new OpenCodeProvider(config.model);
+  const raw = await runStep(
+    "Calling model",
+    async () => provider.chat(messages, { maxTokens: config.maxTokens })
+  );
+  const plan = await runStep("Parsing response", async () => extractJSON(raw));
+  let candidates = await runStep(
+    "Analyzing changes",
+    async () => applyTransforms(plan.commits, plugins, { cwd: process.cwd(), env: process.env })
+  );
+  const plural = candidates.length !== 1;
+  phased.phase(plural ? "Suggested commits" : "Suggested commit");
+  phased.stop();
+  sectionTitle(plural ? "Suggested commits" : "Suggested commit");
+  borderLine();
   candidates = candidates.map((c) => ({
     ...c,
     title: formatCommitTitle(c.title, {
@@ -760,48 +909,67 @@ async function runSplit(config, desired) {
       mode: config.gitmojiMode || "standard"
     })
   }));
-  console.log(chalk2.cyan("\nProposed commits:"));
-  candidates.forEach((c) => {
-    console.log(chalk2.yellow(`\u2022 ${c.title}`));
-    if (c.body) {
-      const indent = "   ";
-      c.body.split("\n").forEach((line) => {
-        if (line.trim().length === 0) console.log(indent);
-        else console.log(indent + chalk2.gray(line));
-      });
+  const fancy = candidates.length > 1;
+  candidates.forEach((c, idx) => {
+    renderCommitBlock({
+      title: c.title,
+      body: c.body,
+      heading: fancy ? `Commit n\xB0${idx + 1}` : void 0,
+      hideMessageLabel: fancy,
+      fancy
+    });
+    if (idx < candidates.length - 1) {
+      borderLine();
+      borderLine();
     }
   });
+  borderLine();
   const { ok } = await inquirer2.prompt([
     {
       type: "list",
       name: "ok",
-      message: "Apply these commit messages?",
+      message: "Use the commits?",
       choices: [
-        { name: "\u25CF Yes", value: true },
-        { name: "\u25CB No", value: false }
+        { name: "Yes", value: true },
+        { name: "No", value: false }
       ],
       default: 0
     }
   ]);
   if (!ok) {
-    console.log("Aborted.");
+    borderLine();
+    abortMessage();
     return;
   }
+  const allChangedFiles = [...new Set(files.map((f) => f.file))];
+  let useFiles = false;
+  if (candidates.every((c) => Array.isArray(c.files) && c.files.length > 0)) {
+    const flat = candidates.flatMap((c) => c.files);
+    const unique = new Set(flat);
+    if ([...unique].every((f) => allChangedFiles.includes(f))) {
+      useFiles = true;
+    }
+  }
+  if (!useFiles) {
+    const buckets = candidates.map(() => []);
+    allChangedFiles.forEach((f, i) => buckets[i % buckets.length].push(f));
+    candidates = candidates.map((c, i) => ({ ...c, files: buckets[i] }));
+    useFiles = true;
+  }
+  let success = 0;
   for (const candidate of candidates) {
-    const pluginErrors = await runValidations(candidate, plugins, {
-      cwd: process.cwd(),
-      env: process.env
-    });
-    const guardErrors = checkCandidate(candidate);
-    const errors = [...pluginErrors, ...guardErrors];
-    if (errors.length) {
-      console.log(chalk2.red("Skipping commit due to errors:"), candidate.title);
-      errors.forEach((e) => console.log(" -", e));
-      continue;
+    await resetIndex();
+    await stageFiles(candidate.files || []);
+    const stagedNow = await getStagedFiles();
+    if (!stagedNow.length) continue;
+    try {
+      await createCommit(candidate.title, candidate.body);
+      success++;
+    } catch (e) {
     }
-    await createCommit(candidate.title, candidate.body);
-    console.log(chalk2.green("Committed: ") + candidate.title);
   }
+  borderLine();
+  finalSuccess({ count: success, startedAt });
   saveSession2({ plan, chosen: candidates, mode: "split" });
 }
 function saveSession2(data) {
@@ -811,9 +979,10 @@ function saveSession2(data) {
 }
 
 // src/workflow/refine.ts
-import chalk3 from "chalk";
-import ora2 from "ora";
-import { readFileSync, existsSync as existsSync3 } from "fs";
+import chalk4 from "chalk";
+import ora3 from "ora";
+import inquirer3 from "inquirer";
+import { readFileSync, existsSync as existsSync3, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "fs";
 import { join as join3 } from "path";
 
 // src/workflow/util.ts
@@ -839,20 +1008,39 @@ function loadSession() {
     return null;
   }
 }
+function saveSession3(session) {
+  const dir = ".git/.aicc-cache";
+  if (!existsSync3(dir)) mkdirSync3(dir, { recursive: true });
+  writeFileSync3(join3(dir, "last-session.json"), JSON.stringify(session, null, 2));
+}
 async function runRefine(config, options) {
-  const spinner = ora2("Loading last session").start();
+  const startedAt = Date.now();
   const session = loadSession();
   if (!session) {
-    spinner.fail("No previous session found.");
+    console.log("No previous session found.");
     return;
   }
-  spinner.succeed("Session loaded");
   const plan = session.plan;
-  const index = options.index ?? 0;
+  const index = options.index ? Number(options.index) - 1 : 0;
   if (!plan.commits[index]) {
     console.log("Invalid index.");
     return;
   }
+  if (process.stdout.isTTY) {
+    await animateHeaderBase();
+    borderLine();
+  }
+  sectionTitle("Original");
+  const original = plan.commits[index];
+  const originalLines = [chalk4.yellow(original.title)];
+  if (original.body) {
+    original.body.split("\n").forEach((line) => {
+      if (line.trim().length === 0) originalLines.push("");
+      else originalLines.push(chalk4.white(line));
+    });
+  }
+  originalLines.forEach((l) => l.trim().length === 0 ? borderLine() : borderLine(l));
+  borderLine();
   const instructions = [];
   if (options.shorter) instructions.push("Make the title shorter but keep meaning.");
   if (options.longer) instructions.push("Add more specificity to the title.");
@@ -866,43 +1054,52 @@ async function runRefine(config, options) {
       return;
     }
   }
+  const phased = createPhasedSpinner(ora3);
+  const runStep = (label, fn) => phased.step(label, fn);
   const provider = new OpenCodeProvider(config.model);
-  const messages = buildRefineMessages({
-    originalPlan: plan,
-    index,
-    instructions,
-    config
+  const messages = await runStep(
+    "Building prompt",
+    async () => buildRefineMessages({ originalPlan: plan, index, instructions, config })
+  );
+  const raw = await runStep(
+    "Calling model",
+    async () => provider.chat(messages, { maxTokens: config.maxTokens })
+  );
+  const refinedPlan = await runStep("Parsing response", async () => extractJSON(raw));
+  refinedPlan.commits[0].title = formatCommitTitle(refinedPlan.commits[0].title, {
+    allowGitmoji: !!config.gitmoji || !!options.emoji,
+    mode: config.gitmojiMode || "standard"
   });
-  const raw = await provider.chat(messages, { maxTokens: config.maxTokens });
-  let refined;
-  try {
-    refined = extractJSON(raw);
-  } catch (e) {
-    console.error("Failed to parse refine response:", e.message);
+  phased.phase("Suggested commit");
+  phased.stop();
+  sectionTitle("Suggested commit");
+  renderCommitBlock({
+    title: refinedPlan.commits[0].title,
+    body: refinedPlan.commits[0].body,
+    titleColor: (s) => chalk4.yellow(s)
+  });
+  borderLine();
+  const { ok } = await inquirer3.prompt([
+    {
+      type: "list",
+      name: "ok",
+      message: "Use the commit?",
+      choices: [
+        { name: "Yes", value: true },
+        { name: "No", value: false }
+      ],
+      default: 0
+    }
+  ]);
+  if (!ok) {
+    borderLine();
+    abortMessage();
     return;
   }
-  {
-    refined.commits[0].title = formatCommitTitle(refined.commits[0].title, {
-      allowGitmoji: !!config.gitmoji || !!options.emoji,
-      mode: config.gitmojiMode || "standard"
-    });
-  }
-  console.log(chalk3.cyan("\nRefined candidate:"));
-  console.log(chalk3.yellow(refined.commits[0].title));
-  if (refined.commits[0].body) {
-    const indent = "   ";
-    refined.commits[0].body.split("\n").forEach((line) => {
-      if (line.trim().length === 0) console.log(indent);
-      else console.log(indent + chalk3.gray(line));
-    });
-  }
-  const accept = await prompt("Accept refined version? (Y/n) ", "y");
-  if (!/^n/i.test(accept)) {
-    plan.commits[index] = refined.commits[0];
-    console.log(chalk3.green("Refinement stored (not retro-committed)."));
-  } else {
-    console.log("Refinement discarded.");
-  }
+  session.plan.commits[index] = refinedPlan.commits[0];
+  saveSession3(session);
+  borderLine();
+  finalSuccess({ count: 1, startedAt });
 }
 
 // src/config.ts
@@ -918,8 +1115,7 @@ var DEFAULTS = {
   maxTokens: parseInt(process.env.AICC_MAX_TOKENS || "512", 10),
   cacheDir: ".git/.aicc-cache",
   plugins: [],
-  verbose: process.env.AICC_VERBOSE === "true",
-  reasoning: process.env.AICC_REASONING || "low"
+  verbose: process.env.AICC_VERBOSE === "true"
 };
 async function loadConfig(cwd = process.cwd()) {
   const explorer = cosmiconfig("aicc");
@@ -935,53 +1131,160 @@ async function loadConfig(cwd = process.cwd()) {
   return cfg;
 }
 
+// package.json
+var package_default = {
+  name: "@kud/ai-conventional-commit-cli",
+  version: "0.4.0",
+  type: "module",
+  description: "Opinionated, style-aware AI assistant for crafting and splitting git commits (opencode-based, provider-agnostic).",
+  bin: {
+    "ai-conventional-commit": "dist/index.js"
+  },
+  files: [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  scripts: {
+    dev: "tsx src/index.ts",
+    build: "tsup src/index.ts --format esm --dts",
+    prepublishOnly: "npm run build",
+    lint: "eslint .",
+    format: "prettier --write .",
+    test: "vitest run",
+    "test:watch": "vitest",
+    commit: "cz"
+  },
+  dependencies: {
+    "@commitlint/config-conventional": "^19.8.1",
+    chalk: "^5.6.0",
+    clipanion: "^3.2.1",
+    cosmiconfig: "^9.0.0",
+    execa: "^9.6.0",
+    "fast-glob": "^3.3.3",
+    inquirer: "^9.3.7",
+    keyv: "^5.5.0",
+    "lru-cache": "^11.2.1",
+    ora: "^8.2.0",
+    pathe: "^2.0.3",
+    "simple-git": "^3.28.0",
+    "strip-ansi": "^7.1.0",
+    zod: "^4.1.5"
+  },
+  devDependencies: {
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^24.3.1",
+    "@typescript-eslint/eslint-plugin": "^8.42.0",
+    "@typescript-eslint/parser": "^8.42.0",
+    "cz-conventional-changelog": "^3.3.0",
+    eslint: "^9.35.0",
+    prettier: "^3.6.2",
+    tsup: "^8.5.0",
+    tsx: "^4.20.5",
+    typescript: "^5.9.2",
+    vitest: "^3.2.4"
+  },
+  config: {
+    commitizen: {
+      path: "cz-conventional-changelog"
+    }
+  },
+  engines: {
+    node: ">=18.17"
+  },
+  license: "MIT"
+};
+
 // src/index.ts
+var pkgVersion = package_default.version || "0.0.0";
 var GenerateCommand = class extends Command {
-  static paths = [[`generate`], [`run`], [`commit`], []];
+  static paths = [[`generate`], []];
+  static usage = Command.Usage({
+    description: "Generate a conventional commit message for staged changes.",
+    details: `Generates a single commit message using AI with style + guardrails.
+Add --gitmoji[-pure] to enable emoji styles.`,
+    examples: [
+      ["Generate a commit with gitmoji style", "ai-conventional-commit generate --gitmoji"]
+    ]
+  });
   gitmoji = Option.Boolean("--gitmoji", false, {
-    description: "Gitmoji mode: emoji acts as type (emoji: subject)"
+    description: "Gitmoji mode (vs --gitmoji-pure): emoji + type (emoji: subject)"
   });
   gitmojiPure = Option.Boolean("--gitmoji-pure", false, {
-    description: "Pure gitmoji mode: emoji: subject (no type)"
+    description: "Pure gitmoji mode (vs --gitmoji): emoji only (emoji: subject)"
+  });
+  model = Option.String("-m,--model", {
+    required: false,
+    description: "Model provider/name (e.g. github-copilot/gpt-5)"
   });
-  reasoning = Option.String("--reasoning", { required: false });
   async execute() {
     const config = await loadConfig();
     if (this.gitmoji || this.gitmojiPure) {
       config.gitmoji = true;
       config.gitmojiMode = this.gitmojiPure ? "gitmoji-pure" : "gitmoji";
     }
-    if (this.reasoning) config.reasoning = this.reasoning;
+    if (this.model) config.model = this.model;
     await runGenerate(config);
   }
 };
 var SplitCommand = class extends Command {
   static paths = [[`split`]];
+  static usage = Command.Usage({
+    description: "Propose multiple smaller conventional commits for current staged diff.",
+    details: `Analyzes staged changes, groups them logically and suggests multiple commit messages.
+Use --max to limit the number of proposals.`,
+    examples: [
+      [
+        "Split into at most 3 commits with gitmoji",
+        "ai-conventional-commit split --max 3 --gitmoji"
+      ]
+    ]
+  });
   max = Option.String("--max", { description: "Max proposed commits", required: false });
-  gitmoji = Option.Boolean("--gitmoji", false);
-  gitmojiPure = Option.Boolean("--gitmoji-pure", false);
-  reasoning = Option.String("--reasoning", { required: false });
+  gitmoji = Option.Boolean("--gitmoji", false, {
+    description: "Gitmoji mode (vs --gitmoji-pure): emoji + type"
+  });
+  gitmojiPure = Option.Boolean("--gitmoji-pure", false, {
+    description: "Pure gitmoji mode (vs --gitmoji): emoji only"
+  });
+  model = Option.String("-m,--model", {
+    required: false,
+    description: "Model provider/name override"
+  });
   async execute() {
     const config = await loadConfig();
     if (this.gitmoji || this.gitmojiPure) {
       config.gitmoji = true;
       config.gitmojiMode = this.gitmojiPure ? "gitmoji-pure" : "gitmoji";
     }
-    if (this.reasoning) config.reasoning = this.reasoning;
+    if (this.model) config.model = this.model;
     await runSplit(config, this.max ? parseInt(this.max, 10) : void 0);
   }
 };
 var RefineCommand = class extends Command {
   static paths = [[`refine`]];
-  shorter = Option.Boolean("--shorter", false);
-  longer = Option.Boolean("--longer", false);
-  scope = Option.String("--scope");
-  emoji = Option.Boolean("--emoji", false);
-  index = Option.String("--index");
-  reasoning = Option.String("--reasoning", { required: false });
+  static usage = Command.Usage({
+    description: "Refine the last (or chosen) commit message with style rules.",
+    details: `Allows targeted improvements: shorter/longer length, inject scope, add emoji, or select a specific index when multiple commits were generated earlier.`,
+    examples: [
+      ["Shorten the last commit message", "ai-conventional-commit refine --shorter"],
+      ["Add a scope to the last commit", "ai-conventional-commit refine --scope ui"]
+    ]
+  });
+  shorter = Option.Boolean("--shorter", false, { description: "Make message more concise" });
+  longer = Option.Boolean("--longer", false, { description: "Expand message with detail" });
+  scope = Option.String("--scope", { description: "Override/add scope (e.g. ui, api)" });
+  emoji = Option.Boolean("--emoji", false, { description: "Add appropriate gitmoji (non-pure)" });
+  index = Option.String("--index", {
+    description: "Select commit index if multiple were generated"
+  });
+  model = Option.String("-m,--model", {
+    required: false,
+    description: "Model provider/name override"
+  });
   async execute() {
     const config = await loadConfig();
-    if (this.reasoning) config.reasoning = this.reasoning;
+    if (this.model) config.model = this.model;
     await runRefine(config, {
       shorter: this.shorter,
       longer: this.longer,
@@ -991,14 +1294,57 @@ var RefineCommand = class extends Command {
     });
   }
 };
+var HelpCommand = class extends Command {
+  static paths = [[`--help`], [`-h`]];
+  // capture explicit help
+  async execute() {
+    this.context.stdout.write(globalHelp() + "\n");
+  }
+};
+function globalHelp() {
+  return `ai-conventional-commit v${pkgVersion}
+
+Usage:
+  ai-conventional-commit [generate] [options]   Generate a commit (default)
+  ai-conventional-commit split [options]        Propose multiple commits
+  ai-conventional-commit refine [options]       Refine last or indexed commit
+
+Global Options:
+  -m, --model <provider/name>   Override model provider/name
+  --gitmoji[-pure]              Gitmoji modes: emoji + type (default) or pure emoji only
+  -h, --help                    Show this help
+  -V, --version                 Show version
+
+Refine Options:
+  --shorter / --longer          Adjust message length
+  --scope <scope>               Add or replace scope
+  --emoji                       Add suitable gitmoji
+  --index <n>                   Select commit index
+
+Examples:
+  ai-conventional-commit --gitmoji
+  ai-conventional-commit --gitmoji-pure
+  ai-conventional-commit split --max 3 --gitmoji
+  ai-conventional-commit refine --scope api --emoji
+`;
+}
+var VersionCommand = class extends Command {
+  static paths = [[`--version`], [`-V`]];
+  async execute() {
+    this.context.stdout.write(`${pkgVersion}
+`);
+  }
+};
 var cli = new Cli({
   binaryLabel: "ai-conventional-commit",
   binaryName: "ai-conventional-commit",
-  binaryVersion: "0.1.0"
+  binaryVersion: pkgVersion
 });
 cli.register(GenerateCommand);
 cli.register(SplitCommand);
 cli.register(RefineCommand);
+cli.register(HelpCommand);
+cli.register(VersionCommand);
 cli.runExit(process.argv.slice(2), {
   stdin: process.stdin,
   stdout: process.stdout,