@webywz/vibe-commit 0.1.9 → 0.1.11

package/README.md

@@ -17,8 +17,10 @@
 </p>
 
 Companion spirit to [diff-vibe](https://github.com/webywz/diff-vibe): commits here, pull requests there.
+Pair walkthrough (EN/中文) and a copy-pasteable helper: [`examples/pair-workflow.md`](./examples/pair-workflow.md) · [`examples/commit-msg.sh`](./examples/commit-msg.sh) (ship in the npm tarball).
 
 与 [diff-vibe](https://github.com/webywz/diff-vibe) 成对：这边写 commit，那边写 PR。
+成对流程与可复制脚本见 [`examples/`](./examples/)（随 npm 包发布）。
 
 ---
 
@@ -65,6 +67,18 @@ Offline heuristic also marks breaking when the staged diff removes public `expor
 
 离线启发式在删掉公开 `export`、或 `package.json` 主版本升级时也会标 breaking；只要 `breaking` 为真就会补上 `BREAKING CHANGE:` footer（`--json` 的 body 与格式化输出一致）。强制 `--breaking` 时 footer 文本即 **subject**；启发式推断 breaking 时仍可用更具体的双语原因。干跑会打一行原因；`--json` 可带 `breakingReason`。
 
+### Pair with diff-vibe · 与 diff-vibe 成对
+
+```bash
+git add -p
+npx --yes @webywz/vibe-commit --commit
+npx --yes @webywz/diff-vibe@^0.1.8 --base main --create
+```
+
+Commits here · PRs there. Full walkthrough (EN/中文) and `commit-msg.sh` live in [`examples/pair-workflow.md`](./examples/pair-workflow.md) and [`examples/commit-msg.sh`](./examples/commit-msg.sh). Companion-side snippets: [diff-vibe examples](https://github.com/webywz/diff-vibe/tree/main/examples).
+
+这边写 commit，那边写 PR。完整成对流程与脚本见 [`examples/`](./examples/)。成对仓库示例：[diff-vibe examples](https://github.com/webywz/diff-vibe/tree/main/examples)。
+
 **Vibes** · 语气
 
 - **pro** — default. Imperative, review-ready. · 默认：祈使句，可进 review。
@@ -158,6 +172,7 @@ console.log(formatCommit(message));
 - npm · [`@webywz/vibe-commit`](https://www.npmjs.com/package/@webywz/vibe-commit)
 - Source · [github.com/webywz/vibe-commit](https://github.com/webywz/vibe-commit)
 - Related · [diff-vibe](https://github.com/webywz/diff-vibe) · [prompt-diff](https://github.com/webywz/prompt-diff)
+- Pair workflow · [examples/pair-workflow.md](./examples/pair-workflow.md)
 - License · [MIT](./LICENSE)
 
 ```bash

package/examples/commit-msg.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Copy-pasteable: stage interactively, then propose / write a commit with vibe-commit.
+# 可复制：交互暂存后，用 vibe-commit 提案 / 真正提交。
+#
+# Pin: @webywz/vibe-commit  ·  Companion: @webywz/diff-vibe@^0.1.8
+# Requires: Node.js 18.18+, git  ·  需要：Node 18.18+、git
+#
+# Typical pair flow · 成对流程：
+#   ./examples/commit-msg.sh
+#   npx --yes @webywz/diff-vibe@^0.1.8 --base main --create
+#
+# Preview only (default) · 只预览（默认）：
+#   DRY_RUN=1 ./examples/commit-msg.sh
+# Write the commit · 真正提交：
+#   COMMIT=1 ./examples/commit-msg.sh
+# Skip interactive add · 跳过交互暂存：
+#   SKIP_ADD=1 COMMIT=1 ./examples/commit-msg.sh
+
+set -euo pipefail
+
+PKG="${PKG:-@webywz/vibe-commit}"
+
+if [[ "${SKIP_ADD:-}" != "1" ]]; then
+  # Interactive stage · 交互暂存
+  git add -p
+fi
+
+if [[ "${COMMIT:-}" == "1" && "${DRY_RUN:-}" != "1" ]]; then
+  # Write the commit · 真正提交
+  npx --yes "$PKG" --commit
+else
+  # Print proposal only · 只打印提案
+  npx --yes "$PKG" --dry-run
+fi

package/examples/pair-workflow.md

@@ -0,0 +1,99 @@
+# Pair workflow · 成对用法
+
+`vibe-commit` writes the commit. `diff-vibe` drafts the PR.
+Use them together on the same branch — offline by default, AI optional.
+
+`vibe-commit` 写 commit，`diff-vibe` 写 PR。
+同一分支上成对用；默认离线，有 Key 再可选 AI。
+
+Pinned packages for this walkthrough · 本示例钉包版本：
+
+- `@webywz/vibe-commit` (this package · 本包)
+- `@webywz/diff-vibe@^0.1.8`
+
+Requires **Node.js 18.18+**, `git`, and (for open/update) [`gh`](https://cli.github.com/).
+
+需要 **Node.js 18.18+**、`git`；开/更新 PR 还需本机有 `gh`。
+
+---
+
+## 1. Commit · 提交
+
+```bash
+git add -p
+npx --yes @webywz/vibe-commit --dry-run    # review the proposal · 先看提案
+npx --yes @webywz/vibe-commit --commit     # write the commit · 真正提交
+```
+
+Or use the short binary / the copy-pasteable helper:
+
+也可全局安装后用短命令，或跑 [`commit-msg.sh`](./commit-msg.sh)：
+
+```bash
+npm i -g @webywz/vibe-commit @webywz/diff-vibe@^0.1.8
+vibe-commit --commit
+# or · 或
+./examples/commit-msg.sh
+```
+
+---
+
+## 2. PR draft · PR 草稿
+
+Diff against the PR base (usually `main`) so commits already on the branch are included.
+
+对比 PR 基线（通常是 `main`），把分支上已提交的改动一并纳入：
+
+```bash
+npx --yes @webywz/diff-vibe@^0.1.8 --base main
+npx --yes @webywz/diff-vibe@^0.1.8 --base main --copy   # clipboard when available · 能复制就复制
+```
+
+Pipe into `gh` without posting yet · 管道进 `gh`（尚未发帖）：
+
+```bash
+gh pr create \
+  --title "$(npx --yes @webywz/diff-vibe@^0.1.8 --base main --title-only)" \
+  --body-file <(npx --yes @webywz/diff-vibe@^0.1.8 --base main --body-only) \
+  --dry-run
+```
+
+Full walkthrough on the companion side: [`diff-vibe` examples/pair-workflow.md](https://github.com/webywz/diff-vibe/blob/main/examples/pair-workflow.md).
+
+成对仓库侧完整流程见 [diff-vibe `examples/pair-workflow.md`](https://github.com/webywz/diff-vibe/blob/main/examples/pair-workflow.md)。
+
+---
+
+## 3. Open or update · 开 PR / 更新
+
+Opt-in flags shell out to `gh`. Nothing is posted without them.
+
+需显式传参才会调 `gh`；不加则只打印草稿。
+
+```bash
+# open a new PR · 开新 PR
+npx --yes @webywz/diff-vibe@^0.1.8 --base main --create
+
+# draft PR · 草稿 PR
+npx --yes @webywz/diff-vibe@^0.1.8 --base main --create --draft
+
+# edit the open PR for this branch · 更新当前分支已开 PR
+npx --yes @webywz/diff-vibe@^0.1.8 --base main --update
+```
+
+`--create` and `--update` are mutually exclusive. `--draft` only pairs with `--create`.
+
+`--create` 与 `--update` 互斥；`--draft` 仅配合 `--create`。
+
+---
+
+## Mental model · 心智模型
+
+| Step · 步骤 | Tool · 工具 | Input · 输入 |
+| --- | --- | --- |
+| Commit message | `vibe-commit` | **staged** diff (`git diff --cached`) |
+| PR title + body | `diff-vibe` | staged + unstaged vs `HEAD`, or vs `--base` merge-base |
+
+Commits here · PRs there. Same offline heuristic family; vibes and AI keys stay optional.
+
+这边写 commit，那边写 PR。同一套离线启发式；文风与 AI Key 都可选。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webywz/vibe-commit",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Stylish conventional commit messages with personality. Offline-first, AI-optional.",
   "keywords": [
     "git",
@@ -40,7 +40,8 @@
     "dist",
     "!dist/**/*.map",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "examples"
   ],
   "engines": {
     "node": ">=18.18"