@webywz/vibe-commit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webywz
+
+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

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# vibe-commit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Stylish conventional commits. Offline-first. AI-optional.**
+
+Stage your files, run one command, get a commit message that looks like you meant it.
+
+一条命令，根据暂存区 diff 写出有品味的 [Conventional Commits](https://www.conventionalcommits.org/)。**无 API Key 也能用**，有 Key 时再可选 AI。
+
+[![CI](https://github.com/webywz/vibe-commit/actions/workflows/ci.yml/badge.svg)](https://github.com/webywz/vibe-commit/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/vibe-commit.svg)](https://www.npmjs.com/package/vibe-commit)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+---
+
+## Demo
+
+```text
+$ git add src/heuristic.ts
+$ vibe-commit
+
+  vibe-commit  ·  heuristic  ·  feat
+
+  1 file  ·  +124  −8
+
+    M  src/heuristic.ts  +124 −8
+
+  proposed
+
+    feat(heuristic): infer conventional commit type from staged diffs
+
+  next  vibe-commit --commit
+```
+
+```text
+$ vibe-commit --vibe playful --commit
+    feat(cli): ship offline heuristic commit messages — quietly useful
+  committed
+```
+
+Pipe-friendly when stdout is not a TTY:
+
+```bash
+git commit -m "$(vibe-commit --dry-run)"
+```
+
+---
+
+## Install · 安装
+
+```bash
+npm install -g vibe-commit
+# or, no install:
+npx vibe-commit
+```
+
+Requires **Node.js 18.18+** and `git`.
+
+```bash
+npm i -g vibe-commit          # 全局安装
+npx vibe-commit               # 一次性运行
+```
+
+---
+
+## Usage · 用法
+
+```bash
+git add -p          # stage the work you actually want to commit
+vibe-commit         # inspect the staged diff, print a proposal
+vibe-commit --commit
+```
+
+| Flag | What it does · 作用 |
+| --- | --- |
+| `--commit` | Run `git commit` with the proposed message · 用生成的信息执行提交 |
+| `--dry-run` | Print only; never commit (default, and wins over `--commit`) |
+| `--type <type>` | Force `feat` / `fix` / `docs` / `style` / `refactor` / `perf` / `test` / `build` / `ci` / `chore` |
+| `--scope <scope>` | Override inferred scope · 覆盖推断出的 scope |
+| `--vibe <style>` | `playful` \| `pro` \| `terse` (default: `pro`) |
+| `--no-ai` | Skip the API even if `OPENAI_API_KEY` is set |
+| `--json` | Machine-readable proposal |
+| `-h`, `--help` | Help |
+| `-v`, `--version` | Version |
+
+### Vibes
+
+- **pro** — default. Imperative, review-ready, conventional.
+- **terse** — headline only, filler words gone.
+- **playful** — a little personality, still safe for a real repo.
+
+默认 **pro**：专业、祈使句、可直接进 code review。`terse` 更短；`playful` 带一点俏皮，但不会变成段子。
+
+---
+
+## How it works · 原理
+
+1. Read **staged** changes only (`git diff --cached`). Unstaged noise is ignored.
+2. **Offline heuristic** (always on): file paths + hunk keywords + added identifiers → `type`, `scope`, `subject`.
+   - `README` / `docs/` → `docs`
+   - `*.test.ts` / `test/` → `test`
+   - `.github/workflows` → `ci`
+   - lockfiles / `package.json` → `chore`
+   - `fix` / `bug` / `crash` in the diff → `fix`
+   - new files / `export function` → `feat`
+3. If `OPENAI_API_KEY` is set, ask an OpenAI-compatible model and **fall back to the heuristic** on any failure.
+4. Print a proposal. With `--commit`, run `git commit` (headline + optional body as two `-m` flags — no shell interpolation).
+
+只看 **已暂存** 的 diff。启发式始终可用；配置了 API Key 才走模型，失败自动回退。
+
+---
+
+## AI (optional)
+
+```bash
+export OPENAI_API_KEY=sk-...
+# optional:
+export OPENAI_MODEL=gpt-4o-mini
+export OPENAI_BASE_URL=https://api.openai.com/v1   # any compatible gateway
+export VIBE_COMMIT_VIBE=pro
+```
+
+Copy `.env.example` if you keep secrets in a file. vibe-commit never sends unstaged files, and it truncates huge diffs.
+
+兼容 OpenAI Chat Completions。没 Key、超时、4xx/5xx → 静默回退到离线启发式，CLI 仍然能给出一条能用的信息。
+
+---
+
+## Library
+
+```ts
+import { proposeHeuristic, formatCommit } from "vibe-commit";
+
+const message = proposeHeuristic({ diff, vibe: "pro" });
+console.log(formatCommit(message));
+// feat(auth): add login
+```
+
+---
+
+## Develop · 开发
+
+```bash
+git clone https://github.com/webywz/vibe-commit
+cd vibe-commit
+npm install
+npm test
+npm run build
+node dist/cli.js --help
+```
+
+| Script |  |
+| --- | --- |
+| `npm test` | Unit + e2e tests (`node:test` + `tsx`) |
+| `npm run build` | Emit `dist/` |
+| `npm run typecheck` | `tsc --noEmit` |
+
+MIT © webywz — see [LICENSE](./LICENSE).

package/dist/ai.d.ts

@@ -0,0 +1,9 @@
+import type { ProposedMessage, StagedDiff, Vibe } from "./types.ts";
+import type { CommitType } from "./types.ts";
+export interface AiContext {
+    diff: StagedDiff;
+    vibe: Vibe;
+    type?: CommitType;
+    scope?: string;
+}
+export declare function proposeWithAi(context: AiContext, env?: NodeJS.ProcessEnv): Promise<ProposedMessage | null>;

package/dist/ai.js

@@ -0,0 +1,83 @@
+import { parseCommit } from "./format.js";
+const MAX_DIFF_CHARS = 12_000;
+export async function proposeWithAi(context, env = process.env) {
+    const apiKey = env.OPENAI_API_KEY?.trim();
+    if (!apiKey)
+        return null;
+    const baseUrl = (env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+    const model = env.OPENAI_MODEL?.trim() || "gpt-4o-mini";
+    try {
+        const response = await fetch(`${baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model,
+                temperature: context.vibe === "playful" ? 0.7 : 0.2,
+                messages: [
+                    { role: "system", content: systemPrompt(context.vibe) },
+                    { role: "user", content: userPrompt(context) },
+                ],
+            }),
+        });
+        if (!response.ok)
+            return null;
+        const payload = (await response.json());
+        const content = payload.choices?.[0]?.message?.content;
+        if (!content)
+            return null;
+        const parsed = parseCommit(content, "ai");
+        if (!parsed)
+            return null;
+        if (context.type)
+            parsed.type = context.type;
+        if (context.scope)
+            parsed.scope = context.scope;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function systemPrompt(vibe) {
+    const vibeLine = vibe === "playful"
+        ? "Tone: witty, still professional; no memes, no emoji, no slang that would embarrass a code review."
+        : vibe === "terse"
+            ? "Tone: as short as possible. Headline only, no body."
+            : "Tone: clear, professional, imperative mood.";
+    return `You write conventional commit messages.
+Return only the commit message, no quotes, no markdown fences.
+Format: type(scope): subject
+Optional body after a blank line.
+Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
+Subject: lowercase, imperative, no trailing period, <= 72 chars.
+${vibeLine}`;
+}
+function userPrompt(context) {
+    const files = context.diff.files
+        .map((file) => {
+        const rename = file.fromPath ? ` (from ${file.fromPath})` : "";
+        return `${file.status} ${file.path}${rename}  +${file.additions} -${file.deletions}`;
+    })
+        .join("\n");
+    const hints = [
+        context.type ? `Forced type: ${context.type}` : null,
+        context.scope ? `Forced scope: ${context.scope}` : null,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const raw = context.diff.raw.slice(0, MAX_DIFF_CHARS);
+    return [
+        hints,
+        "Staged files:",
+        files,
+        "",
+        "Diff:",
+        raw || "(binary or empty hunks)",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+//# sourceMappingURL=ai.js.map

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import pc from "picocolors";
+import { formatCommit } from "./format.js";
+import { commitWithMessage, GitError, inspectStaged } from "./git.js";
+import { helpText, parseArgs, UsageError } from "./parse-args.js";
+import { proposeMessage } from "./propose.js";
+import { renderError, renderProposal, renderVersion } from "./render.js";
+export async function main(argv = process.argv.slice(2)) {
+    let options;
+    try {
+        options = parseArgs(argv);
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            process.stderr.write(`${renderError(error.message)}\n\n${helpText()}`);
+            return 1;
+        }
+        throw error;
+    }
+    if (options.help) {
+        process.stdout.write(helpText());
+        return 0;
+    }
+    if (options.version) {
+        process.stdout.write(`${renderVersion(readVersion())}\n`);
+        return 0;
+    }
+    const piped = !process.stdout.isTTY;
+    try {
+        const diff = inspectStaged();
+        const message = await proposeMessage(diff, {
+            type: options.type,
+            scope: options.scope,
+            vibe: options.vibe,
+            preferAi: !options.noAi,
+        });
+        const formatted = formatCommit(message);
+        const shouldCommit = options.commit && !options.dryRun;
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify({ ...message, formatted }, null, 2)}\n`);
+        }
+        else if (piped) {
+            process.stdout.write(`${formatted}\n`);
+        }
+        else {
+            process.stdout.write(renderProposal(diff, message));
+        }
+        if (shouldCommit) {
+            commitWithMessage(formatted);
+            if (!piped && !options.json) {
+                process.stdout.write(`  ${pc.green("committed")}\n\n`);
+            }
+        }
+        return 0;
+    }
+    catch (error) {
+        const text = error instanceof GitError || error instanceof Error
+            ? error.message
+            : "Unexpected error";
+        process.stderr.write(`${renderError(text)}\n`);
+        return 1;
+    }
+}
+function readVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = join(here, "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function isDirectRun() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(entry).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectRun()) {
+    main().then((code) => process.exit(code), (error) => {
+        process.stderr.write(`${renderError(error instanceof Error ? error.message : "Unexpected error")}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/format.d.ts

@@ -0,0 +1,10 @@
+import { type Engine, type ProposedMessage } from "./types.ts";
+export declare function formatCommit(message: ProposedMessage): string;
+export declare function normalizeSubject(subject: string): string;
+export declare function clip(text: string, max: number): string;
+export declare function parseCommit(text: string, engine?: Engine): ProposedMessage | null;
+export declare function stripFences(text: string): string;
+export declare function splitHeadline(formatted: string): {
+    headline: string;
+    body?: string;
+};

package/dist/format.js

@@ -0,0 +1,72 @@
+import { COMMIT_TYPES, } from "./types.js";
+const TYPE_PATTERN = COMMIT_TYPES.join("|");
+const HEADER_RE = new RegExp(`^(${TYPE_PATTERN})(?:\\(([a-zA-Z0-9][\\w./-]{0,62})\\))?(!)?:\\s*(.+)$`);
+export function formatCommit(message) {
+    const bang = message.breaking ? "!" : "";
+    const head = message.scope
+        ? `${message.type}(${message.scope})${bang}: ${normalizeSubject(message.subject)}`
+        : `${message.type}${bang}: ${normalizeSubject(message.subject)}`;
+    const body = message.body?.trim();
+    return body ? `${head}\n\n${body}` : head;
+}
+export function normalizeSubject(subject) {
+    let text = subject.replace(/\s+/g, " ").trim();
+    text = text.replace(/^[`'"]+|[`'"]+$/g, "");
+    text = text.replace(/\.+$/, "");
+    if (!text)
+        return "update project files";
+    if (/^[A-Z][a-z]/.test(text) && !/^[A-Z]{2,}/.test(text)) {
+        text = text.charAt(0).toLowerCase() + text.slice(1);
+    }
+    return clip(text, 72);
+}
+export function clip(text, max) {
+    if (text.length <= max)
+        return text;
+    const sliced = text.slice(0, max - 1);
+    const atWord = sliced.lastIndexOf(" ");
+    const base = atWord >= 40 ? sliced.slice(0, atWord) : sliced;
+    return `${base.replace(/[ ,;:.-]+$/, "")}…`;
+}
+export function parseCommit(text, engine = "heuristic") {
+    const cleaned = stripFences(text).trim();
+    if (!cleaned)
+        return null;
+    const lines = cleaned.split(/\r?\n/);
+    const headerLine = lines.find((line) => HEADER_RE.test(line.trim()));
+    if (!headerLine)
+        return null;
+    const match = headerLine.trim().match(HEADER_RE);
+    if (!match)
+        return null;
+    const type = match[1];
+    const scope = match[2];
+    const breaking = Boolean(match[3]);
+    const subject = normalizeSubject(match[4] ?? "");
+    const headerIndex = lines.findIndex((line) => line.trim() === headerLine.trim());
+    const rest = lines
+        .slice(headerIndex + 1)
+        .join("\n")
+        .trim();
+    return {
+        type,
+        scope,
+        subject,
+        body: rest || undefined,
+        breaking,
+        engine,
+    };
+}
+export function stripFences(text) {
+    return text
+        .replace(/^\s*```(?:\w+)?\s*/m, "")
+        .replace(/\s*```\s*$/m, "")
+        .replace(/^\s*(?:commit message|message)\s*:\s*/i, "")
+        .trim();
+}
+export function splitHeadline(formatted) {
+    const [headline = formatted, ...rest] = formatted.split("\n");
+    const body = rest.join("\n").trim();
+    return { headline, body: body || undefined };
+}
+//# sourceMappingURL=format.js.map

package/dist/git.d.ts

@@ -0,0 +1,7 @@
+import type { StagedDiff } from "./types.ts";
+export declare class GitError extends Error {
+    constructor(message: string);
+}
+export declare function inspectStaged(cwd?: string): StagedDiff;
+export declare function commitWithMessage(message: string, cwd?: string): string;
+export declare function assertRepo(cwd?: string): void;

package/dist/git.js

@@ -0,0 +1,55 @@
+import { execFileSync } from "node:child_process";
+import { assembleDiff } from "./parse-diff.js";
+export class GitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitError";
+    }
+}
+export function inspectStaged(cwd = process.cwd()) {
+    assertRepo(cwd);
+    const nameStatus = git(["diff", "--cached", "--name-status", "-M"], cwd);
+    const numstat = git(["diff", "--cached", "--numstat", "-M"], cwd);
+    const raw = git(["diff", "--cached", "-M", "--unified=3"], cwd);
+    const diff = assembleDiff(nameStatus, numstat, raw);
+    if (diff.files.length === 0) {
+        throw new GitError("No staged changes. Stage files first: git add -p  (or git add <path>)");
+    }
+    return diff;
+}
+export function commitWithMessage(message, cwd = process.cwd()) {
+    assertRepo(cwd);
+    const [headline, ...rest] = message.split("\n");
+    const body = rest.join("\n").trim();
+    const args = ["commit", "-m", headline ?? message];
+    if (body)
+        args.push("-m", body);
+    return git(args, cwd);
+}
+export function assertRepo(cwd = process.cwd()) {
+    try {
+        const inside = git(["rev-parse", "--is-inside-work-tree"], cwd).trim();
+        if (inside !== "true")
+            throw new Error("not a repo");
+    }
+    catch {
+        throw new GitError("Not a git repository. Run this inside a project with git.");
+    }
+}
+function git(args, cwd) {
+    try {
+        return execFileSync("git", args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        const stderr = error && typeof error === "object" && "stderr" in error
+            ? String(error.stderr)
+            : "";
+        const detail = stderr.trim() || (error instanceof Error ? error.message : "git failed");
+        throw new GitError(detail);
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/heuristic.d.ts

@@ -0,0 +1,15 @@
+import type { CommitType, DiffHunk, ProposedMessage, StagedDiff, StagedFile, Vibe } from "./types.ts";
+export interface HeuristicInput {
+    diff: StagedDiff;
+    type?: CommitType;
+    scope?: string;
+    vibe: Vibe;
+}
+export declare function proposeHeuristic(input: HeuristicInput): ProposedMessage;
+export declare function inferType(diff: StagedDiff): CommitType;
+export declare function primaryRole(path: string): CommitType;
+export declare function classifyPath(path: string): CommitType[];
+export declare function inferScope(files: StagedFile[]): string | undefined;
+export declare function inferSubject(diff: StagedDiff, type: CommitType, scope?: string): string;
+export declare function collectAddedIdentifiers(hunks: DiffHunk[]): string[];
+export declare function stem(path: string): string;