zencommit 0.1.0

package/README.md

@@ -0,0 +1,421 @@
+# zencommit
+
+AI-powered git commit message generator. Analyzes your staged changes and generates meaningful, conventional commit messages using LLMs.
+
+## Features
+
+- **Smart Diff Analysis** - Automatically parses and prioritizes code changes for optimal context
+- **Auto Token Capping** - Intelligently truncates diffs based on model token limits
+- **Multiple Providers** - Supports 20+ AI providers via Vercel AI SDK
+- **Conventional Commits** - Generates messages following conventional commit standards
+- **Interactive Workflow** - Preview, edit, or confirm before committing
+- **Flexible Configuration** - Global, project, and CLI-level configuration options
+- **Secure Credential Storage** - API keys stored securely via Bun's Secrets API
+
+## Installation
+
+### Using npm
+
+```bash
+npm install -g zencommit
+```
+
+### Using Bun
+
+```bash
+bun install -g zencommit
+```
+
+### From Source
+
+```bash
+git clone https://github.com/mboisvertdupras/zencommit.git
+cd zencommit
+bun install
+bun run build:exe
+```
+
+## Quick Start
+
+1. **Set up your API key:**
+
+```bash
+zencommit auth login
+```
+
+2. **Stage your changes and run:**
+
+```bash
+git add .
+zencommit
+```
+
+3. **Review, edit, or confirm the generated commit message.**
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Generate commit message for staged changes
+zencommit
+
+# Auto-commit without confirmation
+zencommit --yes
+
+# Preview without committing
+zencommit --dry-run
+
+# Stage all changes and generate message
+zencommit --all
+
+# Generate message for unstaged changes (preview only)
+zencommit --unstaged
+```
+
+### Command-Line Options
+
+| Flag               | Description                                         |
+| ------------------ | --------------------------------------------------- |
+| `--yes`            | Skip confirmation and commit immediately            |
+| `--dry-run`        | Preview output without committing                   |
+| `--all`            | Stage all changes (`git add -A`) before generating  |
+| `--unstaged`       | Use unstaged diff (never commits unless `--commit`) |
+| `--commit`         | Allow committing with `--unstaged`                  |
+| `--model <id>`     | Override model (e.g., `openai/gpt-4o`)              |
+| `--format <style>` | Commit style: `conventional` or `freeform`          |
+| `--lang <code>`    | Language code (e.g., `en`, `fr`, `es`)              |
+| `--no-body`        | Generate subject line only                          |
+| `-v, -vv, -vvv`    | Increase verbosity level                            |
+| `--`               | Pass additional arguments to `git commit`           |
+
+### Examples
+
+```bash
+# Use a specific model
+zencommit --model anthropic/claude-sonnet-4-20250514
+
+# Generate in French
+zencommit --lang fr
+
+# Freeform style without body
+zencommit --format freeform --no-body
+
+# Pass args to git commit
+zencommit --yes -- --no-verify
+
+# Verbose output for debugging
+zencommit -vv --dry-run
+```
+
+## Authentication
+
+Manage API keys with the `auth` command. Keys are stored securely via Bun's Secrets API and never written to config files.
+
+```bash
+# Interactive login
+zencommit auth login
+
+# Non-interactive login
+zencommit auth login --env-key OPENAI_API_KEY --token sk-...
+
+# Remove stored key
+zencommit auth logout --env-key OPENAI_API_KEY
+
+# Check authentication status
+zencommit auth status
+```
+
+### Supported Environment Variables
+
+| Provider    | Environment Variable                               |
+| ----------- | -------------------------------------------------- |
+| OpenAI      | `OPENAI_API_KEY`                                   |
+| Anthropic   | `ANTHROPIC_API_KEY`                                |
+| Google      | `GOOGLE_GENERATIVE_AI_API_KEY` or `GEMINI_API_KEY` |
+| Azure       | `AZURE_API_KEY`                                    |
+| AWS Bedrock | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`       |
+| Groq        | `GROQ_API_KEY`                                     |
+| Mistral     | `MISTRAL_API_KEY`                                  |
+| xAI         | `XAI_API_KEY`                                      |
+| OpenRouter  | `OPENROUTER_API_KEY`                               |
+| Together AI | `TOGETHER_AI_API_KEY`                              |
+| Perplexity  | `PERPLEXITY_API_KEY`                               |
+| Cohere      | `COHERE_API_KEY`                                   |
+| Cerebras    | `CEREBRAS_API_KEY`                                 |
+| DeepInfra   | `DEEPINFRA_API_KEY`                                |
+| GitLab      | `GITLAB_API_KEY`                                   |
+| Vercel      | `VERCEL_API_KEY`                                   |
+
+## Configuration
+
+Configuration is loaded from multiple sources and merged in order:
+
+1. **Global** - `~/.config/zencommit/config.json`
+2. **Custom path** - `$ZENCOMMIT_CONFIG`
+3. **Project** - `zencommit.json` in repository root
+4. **Inline** - `$ZENCOMMIT_CONFIG_CONTENT` (JSON string)
+
+### Initialize Config
+
+```bash
+zencommit config init
+```
+
+### View Resolved Config
+
+```bash
+zencommit config print
+```
+
+### Validate Config
+
+```bash
+zencommit config validate
+```
+
+### Full Configuration Schema
+
+```json
+{
+  "$schema": "https://zencommit.dev/config.json",
+  "ai": {
+    "model": "openai/gpt-4o",
+    "temperature": 0.2,
+    "maxOutputTokens": 4096,
+    "timeoutMs": 20000,
+    "openaiCompatible": {
+      "baseUrl": "https://example.com/v1",
+      "name": "my-provider"
+    }
+  },
+  "commit": {
+    "style": "conventional",
+    "language": "en",
+    "includeBody": true,
+    "emoji": false
+  },
+  "git": {
+    "diffMode": "staged",
+    "autoStage": false,
+    "confirmBeforeCommit": true
+  },
+  "diff": {
+    "truncateStrategy": "smart",
+    "includeFileList": true,
+    "excludeGitignoreFiles": true,
+    "maxFiles": 200,
+    "smart": {
+      "maxAddedLinesPerHunk": 12,
+      "maxRemovedLinesPerHunk": 12
+    }
+  },
+  "metadata": {
+    "provider": "auto",
+    "fallbackOrder": ["modelsdev", "local"],
+    "providers": {
+      "modelsdev": {
+        "url": "https://models.dev/api.json",
+        "cacheTtlHours": 24
+      },
+      "local": {
+        "path": "./models.metadata.json"
+      }
+    }
+  }
+}
+```
+
+### Configuration Options
+
+#### AI Settings (`ai`)
+
+| Option             | Type   | Default           | Description                              |
+| ------------------ | ------ | ----------------- | ---------------------------------------- |
+| `model`            | string | `"openai/gpt-4o"` | Model ID in `provider/model` format      |
+| `temperature`      | number | `0.2`             | Sampling temperature (0-1)               |
+| `maxOutputTokens`  | number | `4096`            | Maximum tokens in response               |
+| `timeoutMs`        | number | `20000`           | Request timeout in milliseconds          |
+| `openaiCompatible` | object | -                 | Settings for OpenAI-compatible providers |
+
+#### Commit Settings (`commit`)
+
+| Option        | Type    | Default          | Description                      |
+| ------------- | ------- | ---------------- | -------------------------------- |
+| `style`       | string  | `"conventional"` | `"conventional"` or `"freeform"` |
+| `language`    | string  | `"en"`           | Language code for commit message |
+| `includeBody` | boolean | `true`           | Include detailed body in message |
+| `emoji`       | boolean | `false`          | Include emoji in commit subject  |
+
+#### Git Settings (`git`)
+
+| Option                | Type    | Default    | Description                          |
+| --------------------- | ------- | ---------- | ------------------------------------ |
+| `diffMode`            | string  | `"staged"` | `"staged"`, `"unstaged"`, or `"all"` |
+| `autoStage`           | boolean | `false`    | Auto-stage changes before generating |
+| `confirmBeforeCommit` | boolean | `true`     | Prompt before committing             |
+
+#### Diff Settings (`diff`)
+
+| Option                         | Type    | Default   | Description                   |
+| ------------------------------ | ------- | --------- | ----------------------------- |
+| `truncateStrategy`             | string  | `"smart"` | `"smart"` or `"byFile"`       |
+| `includeFileList`              | boolean | `true`    | Include list of changed files |
+| `excludeGitignoreFiles`        | boolean | `true`    | Respect .gitignore            |
+| `maxFiles`                     | number  | `200`     | Maximum files to include      |
+| `smart.maxAddedLinesPerHunk`   | number  | `12`      | Max added lines per hunk      |
+| `smart.maxRemovedLinesPerHunk` | number  | `12`      | Max removed lines per hunk    |
+
+## Supported Providers
+
+zencommit supports any provider compatible with the Vercel AI SDK:
+
+| Provider          | Model Format                | Example                                     |
+| ----------------- | --------------------------- | ------------------------------------------- |
+| OpenAI            | `openai/<model>`            | `openai/gpt-4o`                             |
+| Anthropic         | `anthropic/<model>`         | `anthropic/claude-sonnet-4-20250514`        |
+| Google            | `google/<model>`            | `google/gemini-2.5-pro`                     |
+| Azure OpenAI      | `azure/<deployment>`        | `azure/gpt-4o-deployment`                   |
+| AWS Bedrock       | `bedrock/<model>`           | `bedrock/anthropic.claude-3-5-sonnet`       |
+| Google Vertex     | `vertex/<model>`            | `vertex/gemini-2.0-flash`                   |
+| Vertex Anthropic  | `vertex-anthropic/<model>`  | `vertex-anthropic/claude-sonnet-4-20250514` |
+| Groq              | `groq/<model>`              | `groq/llama-3.3-70b-versatile`              |
+| Mistral           | `mistral/<model>`           | `mistral/mistral-large-latest`              |
+| xAI               | `xai/<model>`               | `xai/grok-2`                                |
+| OpenRouter        | `openrouter/<model>`        | `openrouter/anthropic/claude-3-opus`        |
+| Together AI       | `togetherai/<model>`        | `togetherai/meta-llama/Meta-Llama-3-70B`    |
+| Perplexity        | `perplexity/<model>`        | `perplexity/llama-3.1-sonar-large-128k`     |
+| Cohere            | `cohere/<model>`            | `cohere/command-r-plus`                     |
+| Cerebras          | `cerebras/<model>`          | `cerebras/llama3.1-70b`                     |
+| DeepInfra         | `deepinfra/<model>`         | `deepinfra/meta-llama/Llama-2-70b`          |
+| GitLab            | `gitlab/<model>`            | `gitlab/claude-3-5-sonnet`                  |
+| Vercel            | `vercel/<model>`            | `vercel/v0-1.0-md`                          |
+| AI Gateway        | `gateway/<model>`           | `gateway/openai/gpt-4o`                     |
+| OpenAI Compatible | `openai-compatible/<model>` | `openai-compatible/my-model`                |
+
+### Provider Aliases
+
+For convenience, these aliases are also supported:
+
+- `gemini` → `google`
+- `amazon-bedrock`, `aws-bedrock` → `bedrock`
+- `google-vertex`, `google-vertex-ai` → `vertex`
+- `azure-openai` → `azure`
+- `together.ai` → `togetherai`
+- `xai-grok` → `xai`
+- `open-router` → `openrouter`
+- `vercel-ai-gateway`, `ai-gateway` → `gateway`
+
+## Model Discovery
+
+Explore available models using the `models` command. Model metadata is fetched from [models.dev](https://models.dev) and cached locally.
+
+```bash
+# Search for models
+zencommit models search gpt-4
+
+# Get detailed model info
+zencommit models info openai/gpt-4o
+```
+
+## Smart Diff Truncation
+
+zencommit automatically caps diff content to fit within model token limits:
+
+### `smart` Strategy (default)
+
+1. **File Summary** - Includes compact `name-status` and `numstat` output
+2. **Compact Diff** - Uses `--unified=0` to minimize context lines
+3. **Hunk Prioritization** - Scores and selects most informative hunks:
+   - Prioritizes source code over generated files
+   - Boosts hunks with definitions (functions, classes, types)
+   - Prefers smaller, more focused hunks
+4. **Graceful Degradation** - Falls back to summary-only when needed
+
+### `byFile` Strategy
+
+Distributes token budget proportionally across files, ensuring each file gets a minimum allocation before distributing remaining tokens by size.
+
+## Exit Codes
+
+| Code | Meaning                               |
+| ---- | ------------------------------------- |
+| `0`  | Success                               |
+| `2`  | Configuration or authentication error |
+| `3`  | Git error or no diff available        |
+| `4`  | Model/LLM call error                  |
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) >= 1.0
+- Node.js >= 18 (for npm compatibility)
+
+### Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run directly
+bun src/index.ts
+
+# Lint
+bun run lint
+bun run lint:fix
+
+# Format
+bun run format
+bun run format:check
+
+# Run tests
+bun run test
+
+# Build standalone executable
+bun run build:exe
+```
+
+### Project Structure
+
+```
+zencommit/
+├── src/
+│   ├── index.ts           # CLI entry point (yargs)
+│   ├── commands/          # Command implementations
+│   │   ├── default.ts     # Main commit generation
+│   │   ├── auth.ts        # Authentication commands
+│   │   ├── config.ts      # Configuration commands
+│   │   └── models.ts      # Model discovery commands
+│   ├── config/            # Configuration loading/merging
+│   ├── auth/              # Secrets management
+│   ├── metadata/          # Model metadata providers
+│   ├── git/               # Git operations
+│   ├── llm/               # LLM interactions & tokenization
+│   ├── ui/                # Interactive prompts
+│   └── util/              # Utility functions
+├── tests/                 # Test files
+├── docs/                  # Documentation
+└── bin/                   # Executable scripts
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make your changes following the coding style
+4. Run linting and tests: `bun run lint && bun run test`
+5. Commit using conventional commits: `feat: add my feature`
+6. Push and open a pull request
+
+## License
+
+MIT
+
+## Acknowledgments
+
+- [Vercel AI SDK](https://sdk.vercel.ai/) for unified LLM access
+- [models.dev](https://models.dev) for model metadata
+- [Bun](https://bun.sh/) for fast JavaScript runtime
+- [yargs](https://yargs.js.org/) for CLI parsing
+- [@clack/prompts](https://github.com/bombshell-dev/clack) for beautiful prompts

package/bin/zencommit.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { getInstallPath } from '../scripts/platform.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(__dirname, '..');
+
+let binaryPath;
+try {
+  binaryPath = getInstallPath(pkgRoot);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`zencommit: ${message}`);
+  process.exit(1);
+}
+
+if (!fs.existsSync(binaryPath)) {
+  console.error('zencommit: binary not found.');
+  console.error('zencommit: reinstall the package to download the executable.');
+  process.exit(1);
+}
+
+const child = spawn(binaryPath, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`zencommit: failed to launch: ${message}`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.exit(1);
+  }
+  process.exit(code ?? 1);
+});

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "zencommit",
+  "version": "0.1.0",
+  "module": "./src/index.ts",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "zencommit": "bin/zencommit.js"
+  },
+  "files": ["src", "bin", "scripts"],
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "build:exe": "bun build --compile src/index.ts --outfile dist/zencommit",
+    "postinstall": "node scripts/install.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@ai-sdk/amazon-bedrock": "^4.0.39",
+    "@ai-sdk/anthropic": "^3.0.30",
+    "@ai-sdk/azure": "^3.0.23",
+    "@ai-sdk/cerebras": "^2.0.26",
+    "@ai-sdk/cohere": "^3.0.14",
+    "@ai-sdk/deepinfra": "^2.0.25",
+    "@ai-sdk/gateway": "^3.0.28",
+    "@ai-sdk/google": "^3.0.17",
+    "@ai-sdk/google-vertex": "^4.0.36",
+    "@ai-sdk/groq": "^3.0.18",
+    "@ai-sdk/mistral": "^3.0.15",
+    "@ai-sdk/openai": "^3.0.22",
+    "@ai-sdk/openai-compatible": "^2.0.23",
+    "@ai-sdk/perplexity": "^3.0.14",
+    "@ai-sdk/togetherai": "^2.0.26",
+    "@ai-sdk/vercel": "^2.0.25",
+    "@ai-sdk/xai": "^3.0.42",
+    "@clack/prompts": "^1.0.0",
+    "@dqbd/tiktoken": "^1.0.22",
+    "@gitlab/gitlab-ai-provider": "^3.3.1",
+    "@openrouter/ai-sdk-provider": "^2.1.1",
+    "ai": "^6.0.61",
+    "yargs": "^18.0.0",
+    "yocto-spinner": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.2.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/install.mjs

@@ -0,0 +1,146 @@
+import fs from 'node:fs/promises';
+import { createWriteStream } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import https from 'node:https';
+import http from 'node:http';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { fileURLToPath } from 'node:url';
+import { getAssetName, getInstallPath } from './platform.mjs';
+
+const REPO = 'mboisvertdupras/zencommit';
+const USER_AGENT = 'zencommit-installer';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(__dirname, '..');
+
+const skipChecksum =
+  process.env.ZENCOMMIT_SKIP_CHECKSUM === '1' || process.env.ZENCOMMIT_SKIP_CHECKSUM === 'true';
+
+function getReleaseBase(version) {
+  const base =
+    process.env.ZENCOMMIT_RELEASES_BASE_URL ??
+    `https://github.com/${REPO}/releases/download`;
+  const normalized = base.replace(/\/$/, '');
+  return `${normalized}/v${version}`;
+}
+
+function request(url, redirects = 5) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith('https:') ? https : http;
+    const req = client.get(
+      url,
+      {
+        headers: { 'User-Agent': USER_AGENT },
+      },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        const location = res.headers.location;
+        const isRedirect = [301, 302, 303, 307, 308].includes(status);
+        if (isRedirect && location) {
+          if (redirects <= 0) {
+            res.resume();
+            reject(new Error(`Too many redirects for ${url}`));
+            return;
+          }
+          res.resume();
+          const nextUrl = new URL(location, url).toString();
+          request(nextUrl, redirects - 1).then(resolve, reject);
+          return;
+        }
+        if (status < 200 || status >= 300) {
+          res.resume();
+          reject(new Error(`Request failed: ${status} ${res.statusMessage ?? ''} (${url})`));
+          return;
+        }
+        resolve(res);
+      },
+    );
+    req.on('error', reject);
+  });
+}
+
+async function downloadText(url) {
+  const res = await request(url);
+  const chunks = [];
+  for await (const chunk of res) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function downloadFile(url, destPath) {
+  const res = await request(url);
+  await fs.mkdir(path.dirname(destPath), { recursive: true });
+  const hash = crypto.createHash('sha256');
+  const hashStream = new Transform({
+    transform(chunk, _encoding, callback) {
+      hash.update(chunk);
+      callback(null, chunk);
+    },
+  });
+  await pipeline(res, hashStream, createWriteStream(destPath));
+  return hash.digest('hex');
+}
+
+function parseChecksum(text, assetName) {
+  const lines = text.split(/\r?\n/).map((line) => line.trim());
+  for (const line of lines) {
+    if (!line) continue;
+    const [hash, file] = line.split(/\s+/);
+    if (!hash || !file) continue;
+    const normalized = file.replace(/^\*/, '');
+    if (normalized === assetName) {
+      return hash;
+    }
+  }
+  return null;
+}
+
+async function main() {
+  const pkgRaw = await fs.readFile(path.join(pkgRoot, 'package.json'), 'utf8');
+  const pkg = JSON.parse(pkgRaw);
+  const version = pkg.version;
+  if (!version) {
+    throw new Error('package.json version is missing');
+  }
+
+  const assetName = getAssetName(version);
+  const installPath = getInstallPath(pkgRoot);
+  const tmpPath = `${installPath}.tmp`;
+  const releaseBase = getReleaseBase(version);
+  const assetUrl = `${releaseBase}/${assetName}`;
+  const checksumsUrl = `${releaseBase}/checksums.txt`;
+
+  let expectedHash = null;
+  if (!skipChecksum) {
+    const checksums = await downloadText(checksumsUrl);
+    expectedHash = parseChecksum(checksums, assetName);
+    if (!expectedHash) {
+      throw new Error(`Missing checksum for ${assetName}`);
+    }
+  }
+
+  await fs.rm(installPath, { force: true });
+  await fs.rm(tmpPath, { force: true });
+  const actualHash = await downloadFile(assetUrl, tmpPath);
+
+  if (!skipChecksum && expectedHash && actualHash !== expectedHash) {
+    await fs.rm(tmpPath, { force: true });
+    throw new Error(`Checksum mismatch for ${assetName}`);
+  }
+
+  await fs.rename(tmpPath, installPath);
+  if (process.platform !== 'win32') {
+    await fs.chmod(installPath, 0o755);
+  }
+
+  console.log(`Installed ${assetName}`);
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`zencommit install failed: ${message}`);
+  process.exit(1);
+});