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

package/README.md

@@ -11,8 +11,8 @@ Manual commit messages are noisy, inconsistent, and often miss context. ai-conve
 - Style fingerprinting (average title length, scope usage ratio, gitmoji ratio, top prefixes)
 - Single (`ai-conventional-commit` / `ai-conventional-commit generate`) or multi-commit planning (`ai-conventional-commit split`)
 - Refinement workflow (`ai-conventional-commit refine`) to iteratively tweak a prior result
-- Gitmoji modes: `--gitmoji` (emoji + type) and `--gitmoji-pure` (emoji only)
-- Reasoning depth control (`--reasoning low|medium|high`) influences explanation verbosity
+- Gitmoji modes: `--gitmoji[-pure]` (plain adds emoji + type, pure removes type)
+
 - Privacy tiers governing diff detail sent to model
 - Title normalization + guardrails (length, conventional schema, secret heuristic)
 - Plugin system (transform + validate phases)
@@ -64,12 +64,61 @@ ai-conventional-commit split
 ai-conventional-commit --gitmoji
 # Pure gitmoji (emoji: subject)
 ai-conventional-commit --gitmoji-pure
-# Increase reasoning verbosity
-ai-conventional-commit --reasoning=high
+
+
 # Refine previous session’s first commit making it shorter
 ai-conventional-commit refine --shorter
 ```
 
+## Timed Output
+
+Final success lines now include count + duration, e.g.:
+
+```
+└ ✨ commit created in 850ms.
+└ ✨ 3 commits created in 2.4s.
+```
+
+Durations under 100ms show raw milliseconds; otherwise one decimal second precision.
+
+## Commands
+
+| Command                           | Purpose                                     |
+| --------------------------------- | ------------------------------------------- |
+| `ai-conventional-commit`          | Generate single commit suggestion (default) |
+| `ai-conventional-commit generate` | Same as root (explicit)                     |
+| `ai-conventional-commit split`    | Propose multiple commits (plan)             |
+| `ai-conventional-commit refine`   | Refine last session result                  |
+
+### Help Output
+
+```text
+$ ai-conventional-commit --help
+ai-conventional-commit vX.Y.Z
+
+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 / 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 split --max 3
+  ai-conventional-commit refine --scope api --emoji
+```
+
 ## Gitmoji Modes
 
 | Mode               | Example                   | Notes                                |
@@ -78,17 +127,7 @@ ai-conventional-commit refine --shorter
 | gitmoji            | `✨ feat: add search box` | Emoji + conventional type retained   |
 | gitmoji-pure       | `✨: add search box`      | Type removed, emoji acts as category |
 
-Enable via CLI flags (`--gitmoji` / `--gitmoji-pure`) or config (`gitmoji: true`, `gitmojiMode`).
-
-## Reasoning Depth
-
-Controls verbosity of reasons array in the JSON returned by the model:
-
-- low: minimal
-- medium: balanced
-- high: detailed, more hunk-specific references
-
-Configured with `--reasoning` or in config (`reasoning`).
+Enable via CLI flags (`--gitmoji` or `--gitmoji-pure`, shorthand `--gitmoji[-pure]`) or config (`gitmoji: true`, `gitmojiMode`).
 
 ## Privacy Modes
 
@@ -108,7 +147,7 @@ Uses cosmiconfig; supports JSON, YAML, etc. Example:
   "privacy": "low",
   "gitmoji": true,
   "gitmojiMode": "gitmoji",
-  "reasoning": "low",
+
   "styleSamples": 120,
   "plugins": ["./src/sample-plugin/example-plugin.ts"],
   "maxTokens": 512
@@ -129,7 +168,6 @@ Uses cosmiconfig; supports JSON, YAML, etc. Example:
 - `AICC_DEBUG` (provider debug logs)
 - `AICC_PRINT_LOGS` (stream model raw output)
 - `AICC_DEBUG_PROVIDER=mock` (deterministic JSON response)
-- `AICC_REASONING` (low|medium|high)
 
 ## Conventional Commits Enforcement
 

package/dist/index.cjs

@@ -27,7 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var import_clipanion = require("clipanion");
 
 // src/workflow/generate.ts
-var import_chalk = __toESM(require("chalk"), 1);
+var import_chalk2 = __toESM(require("chalk"), 1);
 var import_ora = __toESM(require("ora"), 1);
 
 // src/git.ts
@@ -218,9 +218,6 @@ var buildGenerationMessages = (opts) => {
   specLines.push(
     "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.`
-  );
   specLines.push("Return ONLY the JSON object. No surrounding text or markdown.");
   specLines.push("Do not add fields not listed in schema.");
   specLines.push("Never fabricate content not present or implied by the diff.");
@@ -570,10 +567,36 @@ var formatCommitTitle = (raw, opts) => {
 var import_node_fs = require("fs");
 var import_node_path2 = require("path");
 var import_inquirer = __toESM(require("inquirer"), 1);
+
+// src/workflow/panel.ts
+var import_chalk = __toESM(require("chalk"), 1);
+function buildPanel(opts) {
+  const termWidth = process.stdout.columns || 80;
+  const contentLines = opts.lines && opts.lines.length ? opts.lines : [];
+  const maxContent = Math.max(
+    opts.title ? stripAnsi(opts.title).length : 0,
+    ...contentLines.map((l) => stripAnsi(l).length)
+  );
+  const innerWidth = Math.min(opts.width || maxContent, termWidth - 4);
+  const pad = (s) => {
+    const visible = stripAnsi(s).length;
+    const needed = innerWidth - visible;
+    return s + " ".repeat(Math.max(0, needed));
+  };
+  const top = "\u250C " + pad(opts.title ? import_chalk.default.bold(opts.title) : "") + " \u2510";
+  const body = contentLines.map((l) => "\u2502 " + pad(l) + " \u2502");
+  const bottom = "\u2514" + "\u2500".repeat(innerWidth + 2) + "\u2518";
+  return [top, ...body, bottom].join("\n");
+}
+function stripAnsi(str) {
+  return str.replace(/\u001B\[[0-9;]*m/g, "");
+}
+
+// src/workflow/generate.ts
 async function animateHeader() {
   const text = "ai-conventional-commit";
   if (!process.stdout.isTTY || process.env.AICC_NO_ANIMATION) {
-    console.log("\n\u250C  " + import_chalk.default.bold(text));
+    console.log("\n\u250C  " + import_chalk2.default.bold(text));
     return;
   }
   const palette = [
@@ -590,7 +613,7 @@ async function animateHeader() {
   ];
   process.stdout.write("\n");
   for (const color of palette) {
-    const frame = import_chalk.default.bold.hex(color)(text);
+    const frame = import_chalk2.default.bold.hex(color)(text);
     process.stdout.write("\r\u250C  " + frame);
     await new Promise((r) => setTimeout(r, 60));
   }
@@ -606,16 +629,25 @@ async function runGenerate(config) {
     console.log("No diff content detected after staging. Aborting.");
     return;
   }
-  await animateHeader();
-  console.log("\u2502");
-  console.log(
-    `\u25C6  ${import_chalk.default.bold(`Detected ${files.length} staged ${files.length === 1 ? "file" : "files"}:`)}`
-  );
-  for (const f of files) console.log("   \u2022 " + f.file);
-  console.log("\u2502");
+  const fileLines = [
+    import_chalk2.default.dim(`Detected ${files.length} staged ${files.length === 1 ? "file" : "files"}:`),
+    ...files.map((f) => "\u2022 " + f.file)
+  ];
+  if (process.stdout.isTTY) {
+    await animateHeader();
+    console.log(
+      buildPanel({
+        title: "Files",
+        lines: fileLines
+      })
+    );
+  } else {
+    console.log("\nFiles:");
+    fileLines.forEach((l) => console.log("  " + l));
+  }
   const spinner = (0, import_ora.default)({ text: " Starting", spinner: "dots" }).start();
   function setPhase(label) {
-    spinner.text = " " + import_chalk.default.bold(label);
+    spinner.text = " " + import_chalk2.default.bold(label);
   }
   async function runStep(label, fn) {
     setPhase(label);
@@ -652,7 +684,7 @@ async function runGenerate(config) {
     async () => applyTransforms(plan.commits, plugins, { cwd: process.cwd(), env: process.env })
   );
   setPhase("Result found");
-  spinner.stopAndPersist({ symbol: "\u25C6", text: " " + import_chalk.default.bold("Result found:") });
+  spinner.stopAndPersist({ symbol: "\u25C6", text: " " + import_chalk2.default.bold("Result found:") });
   candidates = candidates.map((c) => ({
     ...c,
     title: formatCommitTitle(c.title, {
@@ -661,16 +693,24 @@ async function runGenerate(config) {
     })
   }));
   const chosen = candidates[0];
-  console.log("   " + import_chalk.default.white(chosen.title));
+  const resultLines = [import_chalk2.default.white(chosen.title)];
   if (chosen.body) {
-    const indent = "   ";
-    console.log(indent);
     chosen.body.split("\n").forEach((line) => {
-      if (line.trim().length === 0) console.log(indent);
-      else console.log(indent + import_chalk.default.white(line));
+      if (line.trim().length === 0) resultLines.push("");
+      else resultLines.push(import_chalk2.default.white(line));
     });
   }
-  console.log("\u2502");
+  if (process.stdout.isTTY) {
+    console.log(
+      buildPanel({
+        title: "Result",
+        lines: resultLines
+      })
+    );
+  } else {
+    console.log("\nResult:");
+    resultLines.forEach((l) => console.log("  " + l));
+  }
   const pluginErrors = await runValidations(chosen, plugins, {
     cwd: process.cwd(),
     env: process.env
@@ -678,9 +718,18 @@ async function runGenerate(config) {
   const guardErrors = checkCandidate(chosen);
   const errors = [...pluginErrors, ...guardErrors];
   if (errors.length) {
-    console.log(import_chalk.default.red("! Validation issues:"));
-    errors.forEach((e) => console.log("  -", e));
-    console.log("\u2502");
+    const errorLines = ["Validation issues:", ...errors.map((e) => import_chalk2.default.red("\u2022 " + e))];
+    if (process.stdout.isTTY) {
+      console.log(
+        buildPanel({
+          title: "Checks",
+          lines: errorLines
+        })
+      );
+    } else {
+      console.log("\nValidation issues:");
+      errorLines.slice(1).forEach((l) => console.log("  " + l));
+    }
   }
   const yn = await selectYesNo();
   if (!yn) {
@@ -689,7 +738,7 @@ async function runGenerate(config) {
   }
   await createCommit(chosen.title, chosen.body);
   saveSession({ plan, chosen, mode: "single" });
-  console.log(import_chalk.default.green("Commit created."));
+  console.log(import_chalk2.default.green("Commit created."));
 }
 function saveSession(data) {
   const dir = ".git/.aicc-cache";
@@ -713,7 +762,7 @@ async function selectYesNo() {
 }
 
 // src/workflow/split.ts
-var import_chalk2 = __toESM(require("chalk"), 1);
+var import_chalk3 = __toESM(require("chalk"), 1);
 
 // src/cluster.ts
 var topLevel = (file) => file.split("/")[0] || file;
@@ -812,14 +861,14 @@ async function runSplit(config, desired) {
       mode: config.gitmojiMode || "standard"
     })
   }));
-  console.log(import_chalk2.default.cyan("\nProposed commits:"));
+  console.log(import_chalk3.default.cyan("\nProposed commits:"));
   candidates.forEach((c) => {
-    console.log(import_chalk2.default.yellow(`\u2022 ${c.title}`));
+    console.log(import_chalk3.default.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 + import_chalk2.default.gray(line));
+        else console.log(indent + import_chalk3.default.gray(line));
       });
     }
   });
@@ -847,12 +896,12 @@ async function runSplit(config, desired) {
     const guardErrors = checkCandidate(candidate);
     const errors = [...pluginErrors, ...guardErrors];
     if (errors.length) {
-      console.log(import_chalk2.default.red("Skipping commit due to errors:"), candidate.title);
+      console.log(import_chalk3.default.red("Skipping commit due to errors:"), candidate.title);
       errors.forEach((e) => console.log(" -", e));
       continue;
     }
     await createCommit(candidate.title, candidate.body);
-    console.log(import_chalk2.default.green("Committed: ") + candidate.title);
+    console.log(import_chalk3.default.green("Committed: ") + candidate.title);
   }
   saveSession2({ plan, chosen: candidates, mode: "split" });
 }
@@ -863,7 +912,7 @@ function saveSession2(data) {
 }
 
 // src/workflow/refine.ts
-var import_chalk3 = __toESM(require("chalk"), 1);
+var import_chalk4 = __toESM(require("chalk"), 1);
 var import_ora2 = __toESM(require("ora"), 1);
 var import_node_fs3 = require("fs");
 var import_node_path4 = require("path");
@@ -939,19 +988,19 @@ async function runRefine(config, options) {
       mode: config.gitmojiMode || "standard"
     });
   }
-  console.log(import_chalk3.default.cyan("\nRefined candidate:"));
-  console.log(import_chalk3.default.yellow(refined.commits[0].title));
+  console.log(import_chalk4.default.cyan("\nRefined candidate:"));
+  console.log(import_chalk4.default.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 + import_chalk3.default.gray(line));
+      else console.log(indent + import_chalk4.default.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(import_chalk3.default.green("Refinement stored (not retro-committed)."));
+    console.log(import_chalk4.default.green("Refinement stored (not retro-committed)."));
   } else {
     console.log("Refinement discarded.");
   }
@@ -970,8 +1019,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 = (0, import_cosmiconfig.cosmiconfig)("aicc");
@@ -988,52 +1036,103 @@ async function loadConfig(cwd = process.cwd()) {
 }
 
 // src/index.ts
+var import_module = require("module");
+var import_meta = {};
+var require2 = (0, import_module.createRequire)(import_meta.url);
+var pkgVersion = "0.0.0";
+try {
+  const pkg = require2("../package.json");
+  pkgVersion = pkg.version || pkgVersion;
+} catch {
+}
 var GenerateCommand = class extends import_clipanion.Command {
-  static paths = [[`generate`], [`run`], [`commit`], []];
+  static paths = [[`generate`], []];
+  static usage = import_clipanion.Command.Usage({
+    description: "Generate a conventional commit message for staged changes (aliases: run, commit).",
+    details: `Generates a single commit message using AI with style + guardrails.
+Add --gitmoji or --gitmoji-pure to enable emoji styles.`,
+    examples: [
+      ["Generate a commit with gitmoji style", "ai-conventional-commit generate --gitmoji"]
+    ]
+  });
   gitmoji = import_clipanion.Option.Boolean("--gitmoji", false, {
-    description: "Gitmoji mode: emoji acts as type (emoji: subject)"
+    description: "Gitmoji mode (vs --gitmoji-pure): emoji + type (emoji: subject)"
   });
   gitmojiPure = import_clipanion.Option.Boolean("--gitmoji-pure", false, {
-    description: "Pure gitmoji mode: emoji: subject (no type)"
+    description: "Pure gitmoji mode (vs --gitmoji): emoji only (emoji: subject)"
+  });
+  model = import_clipanion.Option.String("-m,--model", {
+    required: false,
+    description: "Model provider/name (e.g. github-copilot/gpt-5)"
   });
-  reasoning = import_clipanion.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 import_clipanion.Command {
   static paths = [[`split`]];
+  static usage = import_clipanion.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 = import_clipanion.Option.String("--max", { description: "Max proposed commits", required: false });
-  gitmoji = import_clipanion.Option.Boolean("--gitmoji", false);
-  gitmojiPure = import_clipanion.Option.Boolean("--gitmoji-pure", false);
-  reasoning = import_clipanion.Option.String("--reasoning", { required: false });
+  gitmoji = import_clipanion.Option.Boolean("--gitmoji", false, {
+    description: "Gitmoji mode (vs --gitmoji-pure): emoji + type"
+  });
+  gitmojiPure = import_clipanion.Option.Boolean("--gitmoji-pure", false, {
+    description: "Pure gitmoji mode (vs --gitmoji): emoji only"
+  });
+  model = import_clipanion.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 import_clipanion.Command {
   static paths = [[`refine`]];
-  shorter = import_clipanion.Option.Boolean("--shorter", false);
-  longer = import_clipanion.Option.Boolean("--longer", false);
-  scope = import_clipanion.Option.String("--scope");
-  emoji = import_clipanion.Option.Boolean("--emoji", false);
-  index = import_clipanion.Option.String("--index");
-  reasoning = import_clipanion.Option.String("--reasoning", { required: false });
+  static usage = import_clipanion.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 = import_clipanion.Option.Boolean("--shorter", false, { description: "Make message more concise" });
+  longer = import_clipanion.Option.Boolean("--longer", false, { description: "Expand message with detail" });
+  scope = import_clipanion.Option.String("--scope", { description: "Override/add scope (e.g. ui, api)" });
+  emoji = import_clipanion.Option.Boolean("--emoji", false, { description: "Add appropriate gitmoji (non-pure)" });
+  index = import_clipanion.Option.String("--index", {
+    description: "Select commit index if multiple were generated"
+  });
+  model = import_clipanion.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,
@@ -1043,14 +1142,57 @@ var RefineCommand = class extends import_clipanion.Command {
     });
   }
 };
+var HelpCommand = class extends import_clipanion.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                     Gitmoji mode (emoji + type)
+  --gitmoji-pure                Gitmoji pure mode (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 split --max 3
+  ai-conventional-commit refine --scope api --emoji
+`;
+}
+var VersionCommand = class extends import_clipanion.Command {
+  static paths = [[`--version`], [`-V`]];
+  async execute() {
+    this.context.stdout.write(`${pkgVersion}
+`);
+  }
+};
 var cli = new import_clipanion.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,