@sabinm677/ccommit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sabin Maharjan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# ccommit
+
+Generate Conventional Commit messages from staged Git changes using Claude Code CLI, OpenCode CLI, or Codex CLI.
+
+## Requirements
+- Bun 1.0+
+- Git 2.0+
+- Claude Code CLI, OpenCode CLI, or Codex CLI configured and available on `PATH`
+
+## Usage
+```bash
+ccommit
+# or from repo root
+bin/ccommit
+```
+
+## Installation
+
+### Via npm (recommended)
+```bash
+npm install -g @sabinm677/ccommit
+```
+
+### From source
+```bash
+git clone https://github.com/sabinm677/ccommit.git
+cd ccommit
+chmod +x bin/ccommit
+ln -sf "$(pwd)/bin/ccommit" ~/.local/bin/ccommit
+```
+
+If needed, add `~/.local/bin` to your `PATH`.
+
+Default mode:
+- Generates a commit message from staged changes
+- Shows the message
+- Prompts `Create commit? [y/N]`
+- Creates commit only when you answer `y` or `yes`
+- In non-interactive mode, commit is auto-cancelled unless `--yes` is used
+
+Show-only mode (no commit created):
+```bash
+ccommit --show
+ccommit -s
+```
+
+Choose provider explicitly:
+```bash
+bin/ccommit -p opencode
+ccommit --provider opencode
+ccommit -p opencode
+ccommit -p codex
+ccommit --yes
+```
+
+## Options
+- `-s`, `--show`: Generate and print message only. Do not prompt or create commit.
+- `-y`, `--yes`: Create commit without interactive confirmation.
+- `-p`, `--provider <claude|opencode|codex>`: Select AI provider for this run.
+- `-h`, `--help`: Show usage help.
+- `-v`, `--version`: Show CLI version.
+- `--verbose`: Print debug details to stderr, including provider failure diagnostics.
+
+ccommit prints the selected provider in the header (including `--show`/`-s` mode):
+```text
+Generated commit message (provider):
+Generated commit message (claude):
+Generated commit message (opencode):
+Generated commit message (codex):
+```
+
+## Config
+Optional config file: `~/.config/ccommit/config.json`
+
+```json
+{
+  "provider": "codex",
+  "providers": {
+    "claude": { "command": "claude", "args": ["-p"] },
+    "opencode": { "command": "opencode", "args": ["run"] },
+    "codex": { "command": "codex", "args": ["exec"] }
+  }
+}
+```
+
+Precedence for provider/command settings: `CLI > env > config > defaults`.
+Default provider: `claude`.
+
+## Exit Codes
+- `0`: success
+- `1`: expected error (for example not a git repo, no staged changes, provider CLI/auth/network failure)
+
+## Development
+Run tests:
+```bash
+bun test
+```
+
+Node compatibility:
+- `ccommit` is Bun-first, but basic CLI invocation with Node remains supported (for example `node bin/ccommit --version`).
+
+## Test Helpers
+For local testing without provider API calls:
+- `CCOMMIT_MOCK_MESSAGE="feat: add feature"` to bypass AI provider call.
+- `CCOMMIT_MOCK_ERROR=AUTH` to force auth error.
+- `CCOMMIT_MOCK_ERROR=NETWORK` to force network error.
+
+Provider env overrides:
+- `CCOMMIT_PROVIDER=claude|opencode|codex`
+- `CCOMMIT_CLAUDE_CMD`, `CCOMMIT_CLAUDE_ARGS`
+- `CCOMMIT_OPENCODE_CMD`, `CCOMMIT_OPENCODE_ARGS`
+- `CCOMMIT_CODEX_CMD`, `CCOMMIT_CODEX_ARGS`
+- `CCOMMIT_PROVIDER_TIMEOUT_MS` (optional, default `60000`)

package/bin/ccommit

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { run } from "../src/main.js";
+
+await run(process.argv.slice(2));
+process.exit(process.exitCode ?? 0);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@sabinm677/ccommit",
+  "version": "0.1.0",
+  "description": "AI-powered Git commit message generator with Conventional Commits output.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Sabin Maharjan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sabinm677/ccommit.git"
+  },
+  "homepage": "https://github.com/sabinm677/ccommit",
+  "bugs": {
+    "url": "https://github.com/sabinm677/ccommit/issues"
+  },
+  "keywords": [
+    "git",
+    "commit",
+    "ai",
+    "conventional-commits",
+    "cli",
+    "claude",
+    "opencode",
+    "codex"
+  ],
+  "files": [
+    "bin",
+    "src"
+  ],
+  "bin": {
+    "ccommit": "./bin/ccommit"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18"
+  }
+}

package/src/ai/generate.js

@@ -0,0 +1,185 @@
+import { spawnSync } from "node:child_process";
+import { AppError } from "../errors/app-error.js";
+import { ERROR_MESSAGES } from "../errors/messages.js";
+import { resolveCommand, resolveProvider } from "./provider-resolution.js";
+
+const DEFAULT_PROVIDER_TIMEOUT_MS = 60_000;
+
+function getProviderErrors() {
+  return {
+    notFound: ERROR_MESSAGES.PROVIDER_NOT_FOUND,
+    auth: ERROR_MESSAGES.PROVIDER_AUTH_FAILURE,
+    network: ERROR_MESSAGES.PROVIDER_NETWORK_FAILURE,
+    timeout: ERROR_MESSAGES.PROVIDER_TIMEOUT,
+  };
+}
+
+function resolveProviderTimeoutMs() {
+  const raw = process.env.CCOMMIT_PROVIDER_TIMEOUT_MS;
+  if (!raw) {
+    return DEFAULT_PROVIDER_TIMEOUT_MS;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_PROVIDER_TIMEOUT_MS;
+  }
+  return parsed;
+}
+
+function classifyCliFailure(stderr = "", stdout = "") {
+  const errors = getProviderErrors();
+  const output = `${stderr}\n${stdout}`.toLowerCase();
+  if (
+    output.includes("unauthorized") ||
+    output.includes("authentication") ||
+    output.includes("api key")
+  ) {
+    return new AppError(errors.auth);
+  }
+  if (
+    output.includes("network") ||
+    output.includes("unable to connect") ||
+    output.includes("failed to fetch") ||
+    output.includes("connect") ||
+    output.includes("timed out") ||
+    output.includes("connection") ||
+    output.includes("econn")
+  ) {
+    return new AppError(errors.network);
+  }
+  return new AppError(ERROR_MESSAGES.UNKNOWN_ERROR);
+}
+
+function summarizeOutput(text = "") {
+  if (typeof text !== "string") {
+    text = text == null ? "" : String(text);
+  }
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return "<empty>";
+  }
+  const max = 600;
+  return trimmed.length > max ? `${trimmed.slice(0, max)}...` : trimmed;
+}
+
+function writeVerboseFailure(options, details) {
+  if (!options.verbose) {
+    return;
+  }
+  process.stderr.write(
+    [
+      "Provider execution failed:",
+      `provider=${details.provider}`,
+      `command=${details.command} ${details.args.join(" ")}`.trim(),
+      `timeout=${details.timeout}ms`,
+      `status=${details.status ?? "null"}`,
+      `error_code=${details.errorCode || "<none>"}`,
+      `error_message=${details.errorMessage || "<none>"}`,
+      `stdout=${summarizeOutput(details.stdout)}`,
+      `stderr=${summarizeOutput(details.stderr)}`,
+      "",
+    ].join("\n"),
+  );
+}
+
+export function generateCommitMessage(prompt, options = {}, config = {}) {
+  const provider = resolveProvider(options, config);
+  const errors = getProviderErrors();
+
+  const mockMessage = process.env.CCOMMIT_MOCK_MESSAGE;
+  if (mockMessage) {
+    return mockMessage;
+  }
+
+  const mockError = process.env.CCOMMIT_MOCK_ERROR;
+  if (mockError === "AUTH") {
+    throw new AppError(errors.auth);
+  }
+  if (mockError === "NETWORK") {
+    throw new AppError(errors.network);
+  }
+
+  const { command, args } = resolveCommand(provider, config);
+  const timeout = resolveProviderTimeoutMs();
+  let result;
+  try {
+    result = spawnSync(command, [...args, prompt], {
+      encoding: "utf8",
+      maxBuffer: 10 * 1024 * 1024,
+      timeout,
+    });
+  } catch (error) {
+    writeVerboseFailure(options, {
+      provider,
+      command,
+      args,
+      timeout,
+      status: null,
+      errorCode: error?.code,
+      errorMessage: error?.message,
+      stdout: "",
+      stderr: "",
+    });
+    if (error?.code === "ENOENT") {
+      throw new AppError(errors.notFound);
+    }
+    if (error?.code === "ETIMEDOUT") {
+      throw new AppError(errors.timeout);
+    }
+    throw new AppError(ERROR_MESSAGES.UNKNOWN_ERROR);
+  }
+
+  if (result.error && result.error.code === "ETIMEDOUT") {
+    writeVerboseFailure(options, {
+      provider,
+      command,
+      args,
+      timeout,
+      status: result.status,
+      errorCode: result.error.code,
+      errorMessage: result.error.message,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    });
+    throw new AppError(errors.timeout);
+  }
+
+  if (result.error && result.error.code === "ENOENT") {
+    writeVerboseFailure(options, {
+      provider,
+      command,
+      args,
+      timeout,
+      status: result.status,
+      errorCode: result.error.code,
+      errorMessage: result.error.message,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    });
+    throw new AppError(errors.notFound);
+  }
+
+  if (result.status !== 0) {
+    const classified = classifyCliFailure(result.stderr, result.stdout);
+    writeVerboseFailure(options, {
+      provider,
+      command,
+      args,
+      timeout,
+      status: result.status,
+      errorCode: result.error?.code,
+      errorMessage: classified.message,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    });
+    throw classified;
+  }
+
+  if (options.verbose) {
+    process.stderr.write(
+      `Provider: ${provider}\nCommand: ${command} ${args.join(" ")}\nTimeout: ${timeout}ms\n`,
+    );
+  }
+
+  return (result.stdout || "").trim();
+}

package/src/ai/prompt-builder.js

@@ -0,0 +1,63 @@
+import { COMMIT_TYPES } from "../commit/types.js";
+
+const MAX_DIFF_CHARS = 120_000;
+
+function extractStagedPaths(diff) {
+  const paths = [];
+  for (const line of diff.split("\n")) {
+    if (!line.startsWith("diff --git ")) {
+      continue;
+    }
+    const match = line.match(/^diff --git a\/(.+) b\/(.+)$/);
+    if (!match) {
+      continue;
+    }
+    paths.push(match[2]);
+  }
+  return paths;
+}
+
+function isDocsOnlyPath(path) {
+  const lower = path.toLowerCase();
+  if (lower.startsWith("docs/")) {
+    return true;
+  }
+  return (
+    lower.endsWith(".md") ||
+    lower.endsWith(".mdx") ||
+    lower.endsWith(".rst") ||
+    lower.endsWith(".txt") ||
+    lower.endsWith(".adoc")
+  );
+}
+
+export function buildPrompt(diff) {
+  const clippedDiff =
+    diff.length > MAX_DIFF_CHARS
+      ? `${diff.slice(0, MAX_DIFF_CHARS)}\n\n[diff truncated for length]`
+      : diff;
+  const stagedPaths = extractStagedPaths(diff);
+  const docsOnly =
+    stagedPaths.length > 0 && stagedPaths.every((path) => isDocsOnlyPath(path));
+
+  const typeGuidance = docsOnly
+    ? "- This change is documentation-only. Use type docs."
+    : "- Choose the type strictly from actual staged changes.";
+
+  return `You are generating a git commit message from a staged diff.
+
+Rules:
+- Use Conventional Commits v1.0.0.
+- Allowed types: ${COMMIT_TYPES.join(", ")}.
+- Format header exactly: <type>[optional scope][optional !]: <description>
+- Description must be concise and imperative.
+- Prefer a single-line commit message. Add body/footer only if essential.
+- Do not claim changes that are not present in the staged diff.
+- Do not use markdown bullets in the commit body.
+- ${typeGuidance}
+- Use BREAKING CHANGE: footer when required.
+- Return only the commit message text with no explanation.
+
+Staged diff:
+${clippedDiff}`;
+}

package/src/ai/provider-resolution.js

@@ -0,0 +1,77 @@
+import { AppError } from "../errors/app-error.js";
+import { ERROR_MESSAGES } from "../errors/messages.js";
+import { isValidProvider } from "./providers.js";
+
+const DEFAULT_PROVIDER = "claude";
+
+function splitArgs(raw) {
+  if (!raw) {
+    return [];
+  }
+  return raw
+    .split(" ")
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+export function resolveProvider(options = {}, config = {}) {
+  const provider =
+    options.provider ||
+    process.env.CCOMMIT_PROVIDER ||
+    config.provider ||
+    DEFAULT_PROVIDER;
+
+  if (!isValidProvider(provider)) {
+    throw new AppError(ERROR_MESSAGES.INVALID_PROVIDER);
+  }
+  return provider;
+}
+
+export function resolveCommand(provider, config = {}) {
+  const defaults =
+    provider === "claude"
+      ? { command: "claude", args: ["-p"] }
+      : provider === "opencode"
+        ? { command: "opencode", args: ["run"] }
+        : { command: "codex", args: ["exec"] };
+
+  if (provider === "claude") {
+    if (process.env.CCOMMIT_CLAUDE_CMD || process.env.CCOMMIT_CLAUDE_ARGS) {
+      return {
+        command: process.env.CCOMMIT_CLAUDE_CMD || defaults.command,
+        args: splitArgs(process.env.CCOMMIT_CLAUDE_ARGS || defaults.args.join(" ")),
+      };
+    }
+  } else if (provider === "opencode") {
+    if (process.env.CCOMMIT_OPENCODE_CMD || process.env.CCOMMIT_OPENCODE_ARGS) {
+      return {
+        command: process.env.CCOMMIT_OPENCODE_CMD || defaults.command,
+        args: splitArgs(
+          process.env.CCOMMIT_OPENCODE_ARGS || defaults.args.join(" "),
+        ),
+      };
+    }
+  } else if (provider === "codex") {
+    if (process.env.CCOMMIT_CODEX_CMD || process.env.CCOMMIT_CODEX_ARGS) {
+      return {
+        command: process.env.CCOMMIT_CODEX_CMD || defaults.command,
+        args: splitArgs(process.env.CCOMMIT_CODEX_ARGS || defaults.args.join(" ")),
+      };
+    }
+  }
+
+  const providerConfig = config.providers?.[provider];
+  if (providerConfig?.command !== undefined || providerConfig?.args !== undefined) {
+    const command = providerConfig.command || defaults.command;
+    const args = providerConfig.args || defaults.args;
+    if (!command || typeof command !== "string") {
+      throw new AppError(ERROR_MESSAGES.INVALID_CONFIG);
+    }
+    if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string")) {
+      throw new AppError(ERROR_MESSAGES.INVALID_CONFIG);
+    }
+    return { command, args };
+  }
+
+  return defaults;
+}

package/src/ai/providers.js

@@ -0,0 +1,5 @@
+export const AI_PROVIDERS = ["claude", "opencode", "codex"];
+
+export function isValidProvider(provider) {
+  return AI_PROVIDERS.includes(provider);
+}

package/src/ai/response-parser.js

@@ -0,0 +1,14 @@
+function stripCodeFence(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("```") && trimmed.endsWith("```")) {
+    return trimmed.replace(/^```[a-zA-Z]*\n?/, "").replace(/\n?```$/, "");
+  }
+  return text;
+}
+
+export function parseCommitMessage(rawOutput) {
+  let text = stripCodeFence(rawOutput).trim();
+  text = text.replace(/^commit message:\s*/i, "").trim();
+  text = text.replace(/^message:\s*/i, "").trim();
+  return text;
+}

package/src/cli/args.js

@@ -0,0 +1,82 @@
+import { AppError } from "../errors/app-error.js";
+import { ERROR_MESSAGES } from "../errors/messages.js";
+import { isValidProvider } from "../ai/providers.js";
+
+export function parseArgs(args) {
+  const options = {
+    help: false,
+    show: false,
+    yes: false,
+    version: false,
+    verbose: false,
+    provider: undefined,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--version" || arg === "-v") {
+      options.version = true;
+      continue;
+    }
+    if (arg === "--show" || arg === "-s") {
+      options.show = true;
+      continue;
+    }
+    if (arg === "--yes" || arg === "-y") {
+      options.yes = true;
+      continue;
+    }
+    if (arg === "--verbose") {
+      options.verbose = true;
+      continue;
+    }
+    if (arg === "--provider" || arg === "-p") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new AppError("Missing value for --provider/-p.");
+      }
+      if (!isValidProvider(value)) {
+        throw new AppError(ERROR_MESSAGES.INVALID_PROVIDER);
+      }
+      options.provider = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--provider=") || arg.startsWith("-p=")) {
+      const value = arg.includes("--provider=")
+        ? arg.slice("--provider=".length)
+        : arg.slice("-p=".length);
+      if (!isValidProvider(value)) {
+        throw new AppError(ERROR_MESSAGES.INVALID_PROVIDER);
+      }
+      options.provider = value;
+      continue;
+    }
+    throw new AppError(`Unknown option: ${arg}`);
+  }
+
+  return options;
+}
+
+export function getHelpText() {
+  return `Usage: ccommit [options]
+
+Generate a Conventional Commit message from staged Git changes.
+
+Options:
+  -s, --show      Show generated message only (do not commit)
+  -y, --yes      Create commit without interactive confirmation
+  -p, --provider  AI provider: claude | opencode | codex
+  -h, --help      Show help
+  -v, --version   Show version
+      --verbose   Print debug information to stderr
+
+Config:
+  ~/.config/ccommit/config.json
+  Precedence: CLI > env > config > defaults
+`;
+}

package/src/cli/confirm.js

@@ -0,0 +1,24 @@
+import { createInterface } from "node:readline";
+import { stdin as input, stdout as output } from "node:process";
+
+export function isInteractiveTerminal() {
+  return Boolean(input.isTTY && output.isTTY);
+}
+
+export async function askForConfirmation(promptText) {
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await new Promise((resolve) => {
+      rl.question(promptText, (value) => {
+        resolve(value ?? "");
+      });
+    });
+    return /^y(es)?$/i.test(answer.trim());
+  } catch {
+    return false;
+  } finally {
+    rl.close();
+    // Bun can keep stdin alive after readline close; pause to allow clean exit.
+    input.pause();
+  }
+}

package/src/cli/exit-codes.js

@@ -0,0 +1,4 @@
+export const EXIT_CODES = {
+  SUCCESS: 0,
+  ERROR: 1,
+};

package/src/commit/normalizer.js

@@ -0,0 +1,36 @@
+import { COMMIT_TYPES } from "./types.js";
+
+function compactWhitespace(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function sanitizeDescription(raw) {
+  const cleaned = compactWhitespace(raw).replace(/[.]+$/, "");
+  if (!cleaned) {
+    return "update project files";
+  }
+  return cleaned.charAt(0).toLowerCase() + cleaned.slice(1);
+}
+
+export function normalizeCommitMessage(message) {
+  const normalized = message.trim();
+  if (!normalized) {
+    return "chore: update project files";
+  }
+
+  const [header, ...rest] = normalized.split("\n");
+  const cleanedHeader = compactWhitespace(header);
+  const matchedType = COMMIT_TYPES.find((type) =>
+    cleanedHeader.toLowerCase().startsWith(`${type}:`),
+  );
+
+  if (matchedType) {
+    return [cleanedHeader, ...rest].join("\n").trim();
+  }
+
+  if (/^[a-z]+(\([^)]+\))?!?:/i.test(cleanedHeader)) {
+    return `chore: ${sanitizeDescription(cleanedHeader.split(":").slice(1).join(":"))}`;
+  }
+
+  return `chore: ${sanitizeDescription(cleanedHeader)}`;
+}

package/src/commit/types.js

@@ -0,0 +1,12 @@
+export const COMMIT_TYPES = [
+  "feat",
+  "fix",
+  "docs",
+  "style",
+  "refactor",
+  "perf",
+  "test",
+  "build",
+  "ci",
+  "chore",
+];

package/src/commit/validator.js

@@ -0,0 +1,30 @@
+import { COMMIT_TYPES } from "./types.js";
+
+const typeGroup = COMMIT_TYPES.join("|");
+const HEADER_REGEX = new RegExp(
+  `^(${typeGroup})(\\([a-z0-9._-]+\\))?(!)?: .+`,
+  "i",
+);
+
+export function isValidCommitMessage(message) {
+  const normalized = message.trim();
+  if (!normalized) {
+    return false;
+  }
+
+  const [header] = normalized.split("\n");
+  if (!HEADER_REGEX.test(header.trim())) {
+    return false;
+  }
+
+  return true;
+}
+
+export function isBreakingChange(message) {
+  const normalized = message.trim();
+  const [header] = normalized.split("\n");
+  if (header.includes("!:")) {
+    return true;
+  }
+  return /\nBREAKING CHANGE:/i.test(`\n${normalized}`);
+}

package/src/config/loader.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { AppError } from "../errors/app-error.js";
+import { ERROR_MESSAGES } from "../errors/messages.js";
+import { isValidProvider } from "../ai/providers.js";
+
+const defaultConfig = Object.freeze({
+  provider: undefined,
+  providers: {
+    claude: { command: undefined, args: undefined },
+    opencode: { command: undefined, args: undefined },
+    codex: { command: undefined, args: undefined },
+  },
+});
+
+export function getConfigPath() {
+  return join(homedir(), ".config", "ccommit", "config.json");
+}
+
+export function loadConfig() {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) {
+    return structuredClone(defaultConfig);
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch {
+    throw new AppError(ERROR_MESSAGES.INVALID_CONFIG_JSON);
+  }
+
+  return normalizeConfig(raw);
+}
+
+function normalizeConfig(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new AppError(ERROR_MESSAGES.INVALID_CONFIG);
+  }
+
+  const provider = raw.provider;
+  if (provider !== undefined) {
+    if (typeof provider !== "string" || !isValidProvider(provider.trim())) {
+      throw new AppError(ERROR_MESSAGES.INVALID_PROVIDER);
+    }
+  }
+
+  const providers = raw.providers;
+  if (
+    providers !== undefined &&
+    (!providers || typeof providers !== "object" || Array.isArray(providers))
+  ) {
+    throw new AppError(ERROR_MESSAGES.INVALID_CONFIG);
+  }
+
+  const normalized = structuredClone(defaultConfig);
+  if (provider !== undefined) {
+    normalized.provider = provider.trim();
+  }
+
+  for (const providerName of ["claude", "opencode", "codex"]) {
+    const value = providers?.[providerName];
+    if (value === undefined) {
+      continue;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new AppError(ERROR_MESSAGES.INVALID_CONFIG);
+    }
+    if (value.command !== undefined) {
+      if (typeof value.command !== "string" || !value.command.trim()) {
+        throw new AppError(ERROR_MESSAGES.INVALID_CONFIG);
+      }
+      normalized.providers[providerName].command = value.command.trim();
+    }
+    if (value.args !== undefined) {
+      if (
+        !Array.isArray(value.args) ||
+        value.args.some((arg) => typeof arg !== "string" || !arg.trim())
+      ) {
+        throw new AppError(ERROR_MESSAGES.INVALID_CONFIG);
+      }
+      normalized.providers[providerName].args = value.args.map((arg) =>
+        arg.trim(),
+      );
+    }
+  }
+
+  return normalized;
+}

package/src/errors/app-error.js

@@ -0,0 +1,9 @@
+export class AppError extends Error {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message);
+    this.name = "AppError";
+  }
+}

package/src/errors/messages.js

@@ -0,0 +1,27 @@
+export const ERROR_MESSAGES = {
+  NO_STAGED_CHANGES:
+    "No staged changes found. Use 'git add' to stage changes first.",
+  NOT_GIT_REPO:
+    "Not a git repository. Please run this command inside a git repository.",
+  PROVIDER_NOT_FOUND:
+    "AI provider CLI not found. Please install and configure the selected provider CLI.",
+  PROVIDER_AUTH_FAILURE:
+    "Failed to authenticate with AI provider API. Please check your API key and provider login.",
+  PROVIDER_NETWORK_FAILURE:
+    "Unable to connect to AI provider API. Please check your internet connection.",
+  PROVIDER_TIMEOUT:
+    "AI provider request timed out. Please retry or increase CCOMMIT_PROVIDER_TIMEOUT_MS.",
+  COMMIT_CANCELLED: "Commit cancelled.",
+  COMMIT_CANCELLED_NON_INTERACTIVE:
+    "Commit cancelled in non-interactive mode. Use --yes to create commit automatically or --show to print message only.",
+  COMMIT_FAILED: "Failed to create git commit with generated message.",
+  INVALID_GENERATED_MESSAGE:
+    "Generated commit message is invalid. Please retry or commit manually.",
+  INVALID_PROVIDER:
+    "Invalid provider. Supported providers: claude, opencode, codex.",
+  INVALID_CONFIG:
+    "Invalid config file at ~/.config/ccommit/config.json.",
+  INVALID_CONFIG_JSON:
+    "Failed to parse config file at ~/.config/ccommit/config.json.",
+  UNKNOWN_ERROR: "An unexpected error occurred while generating commit message.",
+};

package/src/git/create-commit.js

@@ -0,0 +1,17 @@
+import { execFileSync } from "node:child_process";
+import { AppError } from "../errors/app-error.js";
+import { ERROR_MESSAGES } from "../errors/messages.js";
+
+export function createCommit(message, cwd = process.cwd()) {
+  try {
+    execFileSync("git", ["commit", "-F", "-"], {
+      cwd,
+      input: `${message.trim()}\n`,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      maxBuffer: 10 * 1024 * 1024,
+    });
+  } catch {
+    throw new AppError(ERROR_MESSAGES.COMMIT_FAILED);
+  }
+}

package/src/git/repo-check.js

@@ -0,0 +1,14 @@
+import { execFileSync } from "node:child_process";
+
+export function isGitRepository(cwd = process.cwd()) {
+  try {
+    const output = execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return output === "true";
+  } catch {
+    return false;
+  }
+}

package/src/git/staged-diff.js

@@ -0,0 +1,23 @@
+import { execFileSync } from "node:child_process";
+import { AppError } from "../errors/app-error.js";
+import { ERROR_MESSAGES } from "../errors/messages.js";
+
+export function getStagedDiff(cwd = process.cwd()) {
+  let diff = "";
+  try {
+    diff = execFileSync("git", ["diff", "--cached", "--no-ext-diff"], {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch {
+    throw new AppError(ERROR_MESSAGES.NOT_GIT_REPO);
+  }
+
+  if (!diff.trim()) {
+    throw new AppError(ERROR_MESSAGES.NO_STAGED_CHANGES);
+  }
+
+  return diff;
+}

package/src/main.js

@@ -0,0 +1,102 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { parseArgs, getHelpText } from "./cli/args.js";
+import { EXIT_CODES } from "./cli/exit-codes.js";
+import { isGitRepository } from "./git/repo-check.js";
+import { getStagedDiff } from "./git/staged-diff.js";
+import { createCommit } from "./git/create-commit.js";
+import { ERROR_MESSAGES } from "./errors/messages.js";
+import { AppError } from "./errors/app-error.js";
+import { writeStdout, writeStderr } from "./output/writer.js";
+import { askForConfirmation, isInteractiveTerminal } from "./cli/confirm.js";
+import { buildPrompt } from "./ai/prompt-builder.js";
+import { generateCommitMessage } from "./ai/generate.js";
+import { resolveProvider } from "./ai/provider-resolution.js";
+import { parseCommitMessage } from "./ai/response-parser.js";
+import { isValidCommitMessage } from "./commit/validator.js";
+import { normalizeCommitMessage } from "./commit/normalizer.js";
+import { loadConfig } from "./config/loader.js";
+
+function getVersion() {
+  const currentFile = fileURLToPath(import.meta.url);
+  const root = join(dirname(currentFile), "..");
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  return pkg.version;
+}
+
+export async function run(args = []) {
+  try {
+    const options = parseArgs(args);
+
+    if (options.help) {
+      writeStdout(getHelpText());
+      process.exitCode = EXIT_CODES.SUCCESS;
+      return;
+    }
+
+    if (options.version) {
+      writeStdout(`${getVersion()}\n`);
+      process.exitCode = EXIT_CODES.SUCCESS;
+      return;
+    }
+
+    if (!isGitRepository()) {
+      throw new AppError(ERROR_MESSAGES.NOT_GIT_REPO);
+    }
+
+    const config = loadConfig();
+    const provider = resolveProvider(options, config);
+    const diff = getStagedDiff();
+    const prompt = buildPrompt(diff);
+    const rawMessage = generateCommitMessage(prompt, options, config);
+    let commitMessage = parseCommitMessage(rawMessage);
+
+    if (!isValidCommitMessage(commitMessage)) {
+      commitMessage = normalizeCommitMessage(commitMessage);
+    }
+
+    if (!isValidCommitMessage(commitMessage)) {
+      throw new AppError(ERROR_MESSAGES.INVALID_GENERATED_MESSAGE);
+    }
+
+    if (options.show) {
+      writeStdout(
+        `Generated commit message (${provider}):\n\n${commitMessage.trim()}\n`,
+      );
+      process.exitCode = EXIT_CODES.SUCCESS;
+      return;
+    }
+
+    writeStdout(
+      `Generated commit message (${provider}):\n\n${commitMessage.trim()}\n\n`,
+    );
+    let confirmed = false;
+
+    if (options.yes) {
+      confirmed = true;
+    } else if (!isInteractiveTerminal()) {
+      writeStderr(`${ERROR_MESSAGES.COMMIT_CANCELLED_NON_INTERACTIVE}\n`);
+      process.exitCode = EXIT_CODES.SUCCESS;
+      return;
+    } else {
+      confirmed = await askForConfirmation("Create commit? [y/N] ");
+      writeStdout("\n");
+    }
+
+    if (!confirmed) {
+      writeStderr(`${ERROR_MESSAGES.COMMIT_CANCELLED}\n`);
+      process.exitCode = EXIT_CODES.SUCCESS;
+      return;
+    }
+
+    createCommit(commitMessage);
+    writeStdout("Commit created.\n");
+    process.exitCode = EXIT_CODES.SUCCESS;
+  } catch (error) {
+    const message =
+      error instanceof AppError ? error.message : ERROR_MESSAGES.UNKNOWN_ERROR;
+    writeStderr(`${message}\n`);
+    process.exitCode = EXIT_CODES.ERROR;
+  }
+}

package/src/output/writer.js

@@ -0,0 +1,7 @@
+export function writeStdout(message) {
+  process.stdout.write(message);
+}
+
+export function writeStderr(message) {
+  process.stderr.write(message);
+}