@zjex/git-workflow 0.2.19 → 0.2.21

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zjex/git-workflow",
-	"version": "0.2.19",
+	"version": "0.2.21",
 	"description": "🚀 极简的 Git 工作流 CLI 工具，让分支管理和版本发布变得轻松愉快",
 	"type": "module",
 	"bin": {
@@ -42,10 +42,12 @@
 		"@inquirer/prompts": "^7.0.0",
 		"boxen": "^8.0.1",
 		"cac": "^6.7.14",
-		"ora": "^9.0.0"
+		"ora": "^9.0.0",
+		"semver": "^7.7.3"
 	},
 	"devDependencies": {
 		"@types/node": "^25.0.3",
+		"@types/semver": "^7.7.1",
 		"changelogen": "^0.6.2",
 		"husky": "^9.1.7",
 		"tsup": "^8.5.1",

package/src/commands/commit.ts

@@ -5,7 +5,11 @@ import { colors, theme, execOutput, divider } from "../utils.js";
 import { getConfig } from "../config.js";
 import { generateAICommitMessage, isAICommitAvailable } from "../ai-service.js";
 
-// Conventional Commits 类型 + Gitmoji
+/**
+ * Conventional Commits 类型定义 + Gitmoji
+ * 遵循 https://www.conventionalcommits.org/ 规范
+ * 使用 https://gitmoji.dev/ emoji
+ */
 const DEFAULT_COMMIT_TYPES = [
   { type: "feat", emoji: "✨", description: "新功能" },
   { type: "fix", emoji: "🐛", description: "修复 Bug" },
@@ -17,11 +21,15 @@ const DEFAULT_COMMIT_TYPES = [
   { type: "build", emoji: "📦", description: "构建/依赖相关" },
   { type: "ci", emoji: "👷", description: "CI/CD 相关" },
   { type: "chore", emoji: "🔧", description: "其他杂项" },
-  { type: "revert", emoji: "⏪", description: "回退提交" },
 ] as const;
 
 type CommitType = (typeof DEFAULT_COMMIT_TYPES)[number]["type"];
 
+/**
+ * 获取提交类型列表（支持自定义 emoji）
+ * @param config 用户配置
+ * @returns 提交类型列表
+ */
 function getCommitTypes(config: ReturnType<typeof getConfig>) {
   const customEmojis = config.commitEmojis || {};
   return DEFAULT_COMMIT_TYPES.map((item) => ({
@@ -30,11 +38,18 @@ function getCommitTypes(config: ReturnType<typeof getConfig>) {
   }));
 }
 
+/**
+ * 文件状态接口
+ */
 interface FileStatus {
-  status: string;
-  file: string;
+  status: string; // M=修改, A=新增, D=删除, ?=未跟踪
+  file: string; // 文件路径
 }
 
+/**
+ * 解析 git status 输出
+ * @returns 已暂存和未暂存的文件列表
+ */
 function parseGitStatus(): { staged: FileStatus[]; unstaged: FileStatus[] } {
   const output = execOutput("git status --porcelain");
   if (!output) return { staged: [], unstaged: [] };
@@ -44,9 +59,9 @@ function parseGitStatus(): { staged: FileStatus[]; unstaged: FileStatus[] } {
 
   for (const line of output.split("\n")) {
     if (!line) continue;
-    const indexStatus = line[0];
-    const workTreeStatus = line[1];
-    const file = line.slice(3);
+    const indexStatus = line[0]; // 暂存区状态
+    const workTreeStatus = line[1]; // 工作区状态
+    const file = line.slice(3); // 文件路径
 
     // 已暂存的更改 (index 有状态)
     if (indexStatus !== " " && indexStatus !== "?") {
@@ -63,23 +78,33 @@ function parseGitStatus(): { staged: FileStatus[]; unstaged: FileStatus[] } {
   return { staged, unstaged };
 }
 
+/**
+ * 格式化文件状态显示（带颜色）
+ * @param status 文件状态
+ * @returns 带颜色的状态字符串
+ */
 function formatFileStatus(status: string): string {
   const statusMap: Record<string, string> = {
-    M: colors.yellow("M"),
-    A: colors.green("A"),
-    D: colors.red("D"),
-    R: colors.yellow("R"),
-    C: colors.yellow("C"),
-    "?": colors.green("?"),
+    M: colors.yellow("M"), // 修改
+    A: colors.green("A"), // 新增
+    D: colors.red("D"), // 删除
+    R: colors.yellow("R"), // 重命名
+    C: colors.yellow("C"), // 复制
+    "?": colors.green("?"), // 未跟踪
   };
   return statusMap[status] || status;
 }
 
+/**
+ * 交互式提交命令
+ * 支持 AI 自动生成和手动编写两种模式
+ * 遵循 Conventional Commits 规范
+ */
 export async function commit(): Promise<void> {
   const config = getConfig();
   let { staged, unstaged } = parseGitStatus();
 
-  // 如果有未暂存的更改，根据配置决定是否自动暂存
+  // ========== 步骤 1: 处理未暂存的文件 ==========
   if (unstaged.length > 0) {
     const autoStage = config.autoStage ?? true;
 
@@ -131,7 +156,7 @@ export async function commit(): Promise<void> {
     }
   }
 
-  // 没有暂存的更改
+  // ========== 步骤 2: 检查是否有文件可提交 ==========
   if (staged.length === 0) {
     console.log(colors.yellow("工作区干净，没有需要提交的更改"));
     return;
@@ -144,7 +169,7 @@ export async function commit(): Promise<void> {
   }
   divider();
 
-  // 询问用户选择手动还是 AI 生成
+  // ========== 步骤 3: 选择提交方式（AI 或手动）==========
   const aiAvailable = isAICommitAvailable(config);
   let commitMode: "ai" | "manual" = "manual";
 
@@ -167,10 +192,12 @@ export async function commit(): Promise<void> {
     });
   }
 
-  let message: string;
+  // 初始化 commit message 变量
+  let message: string = "";
 
+  // ========== 步骤 4: 生成 commit message ==========
+  // AI 生成模式
   if (commitMode === "ai") {
-    // AI 生成模式
     const spinner = ora("AI 正在分析代码变更...").start();
 
     try {
@@ -208,11 +235,12 @@ export async function commit(): Promise<void> {
     }
   }
 
+  // 手动输入模式
   if (commitMode === "manual") {
-    // 手动输入模式（原有逻辑）
     message = await buildManualCommitMessage(config);
   }
 
+  // ========== 步骤 5: 预览并确认提交 ==========
   divider();
   console.log("提交信息预览:");
   console.log(colors.green(message));
@@ -232,9 +260,23 @@ export async function commit(): Promise<void> {
     return;
   }
 
+  // ========== 步骤 6: 执行提交 ==========
   const spinner = ora("正在提交...").start();
 
   try {
+    // 提交前再次检查是否有暂存的文件
+    const finalStatus = parseGitStatus();
+    if (finalStatus.staged.length === 0) {
+      spinner.fail("没有暂存的文件可以提交");
+      console.log("");
+      console.log(colors.yellow("请先暂存文件:"));
+      console.log(colors.cyan("  git add <file>"));
+      console.log(colors.dim("  或"));
+      console.log(colors.cyan("  git add -A"));
+      console.log("");
+      return;
+    }
+
     // 使用 -m 参数，需要转义引号
     const escapedMessage = message.replace(/"/g, '\\"');
     execSync(`git commit -m "${escapedMessage}"`, { stdio: "pipe" });
@@ -245,14 +287,26 @@ export async function commit(): Promise<void> {
     console.log(colors.dim(`commit: ${commitHash}`));
   } catch (error) {
     spinner.fail("提交失败");
+    console.log("");
+
+    // 显示详细错误信息
     if (error instanceof Error) {
-      console.log(colors.red(error.message));
+      console.log(colors.red("错误信息:"));
+      console.log(colors.dim(`  ${error.message}`));
     }
+
+    console.log("");
+    console.log(colors.yellow("你可以手动执行以下命令:"));
+    console.log(colors.cyan(`  git commit -m "${message}"`));
+    console.log("");
   }
 }
 
 /**
  * 手动构建 commit message
+ * 通过交互式问答收集信息，构建符合 Conventional Commits 规范的提交信息
+ * @param config 用户配置
+ * @returns 完整的 commit message
  */
 async function buildManualCommitMessage(
   config: ReturnType<typeof getConfig>
@@ -260,23 +314,30 @@ async function buildManualCommitMessage(
   // 获取提交类型（支持自定义 emoji）
   const commitTypes = getCommitTypes(config);
 
-  // 选择提交类型
+  // ========== 1. 选择提交类型 ==========
   const typeChoice = await select({
     message: "选择提交类型:",
-    choices: commitTypes.map((t) => ({
-      name: `${t.emoji}  ${t.type.padEnd(10)} ${colors.dim(t.description)}`,
-      value: t,
-    })),
+    choices: commitTypes.map((t) => {
+      // 使用固定宽度格式化，不依赖 emoji 宽度
+      const typeText = t.type.padEnd(10);
+      // 针对 refactor 特殊处理，因为 ♻️ emoji 在不同终端宽度不一致
+      const spacing = t.type === "refactor" ? "   " : "  ";
+      return {
+        name: `${t.emoji}${spacing}${typeText} ${colors.dim(t.description)}`,
+        value: t,
+      };
+    }),
+    pageSize: commitTypes.length, // 显示所有选项，不滚动
     theme,
   });
 
-  // 输入 scope (可选)
+  // ========== 2. 输入 scope (可选) ==========
   const scope = await input({
     message: "输入影响范围 scope (可跳过):",
     theme,
   });
 
-  // 输入简短描述
+  // ========== 3. 输入简短描述 (必填) ==========
   const subject = await input({
     message: "输入简短描述:",
     validate: (value) => {
@@ -287,13 +348,13 @@ async function buildManualCommitMessage(
     theme,
   });
 
-  // 输入详细描述 (可选)
+  // ========== 4. 输入详细描述 (可选) ==========
   const body = await input({
     message: "输入详细描述 (可跳过):",
     theme,
   });
 
-  // 是否有破坏性变更
+  // ========== 5. 是否有破坏性变更 ==========
   const hasBreaking = await select({
     message: "是否包含破坏性变更 (BREAKING CHANGE)?",
     choices: [
@@ -312,13 +373,13 @@ async function buildManualCommitMessage(
     });
   }
 
-  // 关联 Issue (可选)
+  // ========== 6. 关联 Issue (可选) ==========
   const issues = await input({
     message: "关联 Issue (如 #123, 可跳过):",
     theme,
   });
 
-  // 构建 commit message
+  // ========== 7. 构建 commit message ==========
   const { type, emoji } = typeChoice;
   const scopePart = scope ? `(${scope})` : "";
   const breakingMark = hasBreaking ? "!" : "";
@@ -330,7 +391,7 @@ async function buildManualCommitMessage(
   // Header: [emoji] type(scope)!: subject
   let message = `${emojiPrefix}${type}${scopePart}${breakingMark}: ${subject}`;
 
-  // Body
+  // Body (可选)
   if (body || hasBreaking || issues) {
     message += "\n";
 

package/src/commands/help.ts

@@ -25,7 +25,7 @@ Tag 命令:
   gw tag:delete                   删除 tag
   gw td                           同上 (别名)
 
-  gw tag:update                   修改 tag 消息
+  gw tag:update                   重命名 tag
   gw tu                           同上 (别名)
 
 发布命令:
@@ -42,6 +42,9 @@ Tag 命令:
   gw update                       检查并更新到最新版本
   gw upt                          同上 (别名)
 
+清理命令:
+  gw clean                        清理缓存文件
+
 Stash 命令:
   gw stash                        交互式管理 stash
   gw s                            同上 (别名)

package/src/commands/tag.ts

@@ -417,7 +417,7 @@ export async function deleteTag(): Promise<void> {
 }
 
 /**
- * 修改 tag（重新打标签）
+ * 修改 tag 名称（重命名 tag）
  */
 export async function updateTag(): Promise<void> {
   const fetchSpinner = ora("正在获取 tags...").start();
@@ -438,47 +438,71 @@ export async function updateTag(): Promise<void> {
   const choices = tags.map((tag) => ({ name: tag, value: tag }));
   choices.push({ name: "取消", value: "__cancel__" });
 
-  const tagToUpdate = await select({
-    message: "选择要修改的 tag:",
+  const oldTag = await select({
+    message: "选择要重命名的 tag:",
     choices,
     theme,
   });
 
-  if (tagToUpdate === "__cancel__") {
+  if (oldTag === "__cancel__") {
     console.log(colors.yellow("已取消"));
     return;
   }
 
-  const newMessage = await input({
-    message: "输入新的 tag 消息:",
-    default: `Release ${tagToUpdate}`,
+  console.log("");
+  console.log(colors.dim(`当前 tag: ${oldTag}`));
+  console.log("");
+
+  const newTag = await input({
+    message: "输入新的 tag 名称:",
+    default: oldTag,
     theme,
   });
 
-  if (!newMessage) {
+  if (!newTag || newTag === oldTag) {
     console.log(colors.yellow("已取消"));
     return;
   }
 
+  // 检查新 tag 是否已存在
+  const existingTags = execOutput("git tag -l").split("\n").filter(Boolean);
+  if (existingTags.includes(newTag)) {
+    console.log(colors.red(`Tag ${newTag} 已存在，无法重命名`));
+    return;
+  }
+
   divider();
 
-  const spinner = ora(`正在更新 tag: ${tagToUpdate}`).start();
+  const spinner = ora(`正在重命名 tag: ${oldTag} → ${newTag}`).start();
 
   try {
+    // 获取旧 tag 的 commit 和消息
+    const commit = execOutput(`git rev-list -n 1 "${oldTag}"`).trim();
+    const message = execOutput(
+      `git tag -l --format='%(contents)' "${oldTag}"`
+    ).trim();
+
+    // 创建新 tag（指向同一个 commit）
+    if (message) {
+      execSync(`git tag -a "${newTag}" "${commit}" -m "${message}"`, {
+        stdio: "pipe",
+      });
+    } else {
+      execSync(`git tag "${newTag}" "${commit}"`, { stdio: "pipe" });
+    }
+
     // 删除旧 tag
-    execSync(`git tag -d "${tagToUpdate}"`, { stdio: "pipe" });
-    // 创建新 tag（在同一个 commit 上）
-    execSync(`git tag -a "${tagToUpdate}" -m "${newMessage}"`, {
-      stdio: "pipe",
-    });
-    spinner.succeed(`Tag 已更新: ${tagToUpdate}`);
-  } catch {
-    spinner.fail("tag 更新失败");
+    execSync(`git tag -d "${oldTag}"`, { stdio: "pipe" });
+
+    spinner.succeed(`Tag 已重命名: ${oldTag} → ${newTag}`);
+  } catch (error) {
+    spinner.fail("tag 重命名失败");
+    console.log(colors.red(String(error)));
     return;
   }
 
   const pushRemote = await select({
-    message: "是否推送到远程（会强制覆盖）?",
+    message: "是否同步到远程?",
     choices: [
       { name: "是", value: true },
       { name: "否", value: false },
@@ -487,13 +511,16 @@ export async function updateTag(): Promise<void> {
   });
 
   if (pushRemote) {
-    const pushSpinner = ora("正在推送到远程...").start();
+    const pushSpinner = ora("正在同步到远程...").start();
     try {
-      execSync(`git push origin "${tagToUpdate}" --force`, { stdio: "pipe" });
-      pushSpinner.succeed(`Tag 已推送: ${tagToUpdate}`);
+      // 推送新 tag
+      execSync(`git push origin "${newTag}"`, { stdio: "pipe" });
+      // 删除远程旧 tag
+      execSync(`git push origin --delete "${oldTag}"`, { stdio: "pipe" });
+      pushSpinner.succeed(`远程 tag 已同步: ${oldTag} → ${newTag}`);
     } catch {
       pushSpinner.warn(
-        `远程推送失败，可稍后手动执行: git push origin ${tagToUpdate} --force`
+        `远程同步失败，可稍后手动执行:\n  git push origin ${newTag}\n  git push origin --delete ${oldTag}`
       );
     }
   }

package/src/commands/update.ts

@@ -1,8 +1,28 @@
 import { execSync } from "child_process";
 import ora from "ora";
 import boxen from "boxen";
+import semver from "semver";
+import { existsSync, unlinkSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 import { colors } from "../utils.js";
 
+const CACHE_FILE = ".gw-update-check";
+
+/**
+ * 清理更新缓存文件
+ */
+function clearUpdateCache(): void {
+  try {
+    const cacheFile = join(homedir(), CACHE_FILE);
+    if (existsSync(cacheFile)) {
+      unlinkSync(cacheFile);
+    }
+  } catch {
+    // 静默失败
+  }
+}
+
 /**
  * 获取 npm 上的最新版本
  */
@@ -42,11 +62,12 @@ export async function update(currentVersion: string): Promise<void> {
 
     spinner.stop();
 
-    if (latestVersion === currentVersion) {
+    // 使用 semver 比较版本
+    if (semver.gte(currentVersion, latestVersion)) {
       console.log(
         boxen(
           [
-            colors.bold("✅ 已是最新版本"),
+            colors.green(colors.bold("✅ 已是最新版本")),
             "",
             `当前版本: ${colors.green(currentVersion)}`,
           ].join("\n"),
@@ -63,21 +84,30 @@ export async function update(currentVersion: string): Promise<void> {
     }
 
     // 有新版本
+    const versionText = `${currentVersion}  →  ${latestVersion}`;
+    const maxWidth = Math.max(
+      "🎉 发现新版本！".length,
+      versionText.length,
+      "✨ 更新完成！".length,
+      "请重新打开终端使用新版本".length
+    );
+
     console.log(
       boxen(
         [
-          colors.bold("🎉 发现新版本！"),
+          colors.yellow(colors.bold("🎉 发现新版本！")),
           "",
           `${colors.dim(currentVersion)}  →  ${colors.green(
             colors.bold(latestVersion)
           )}`,
         ].join("\n"),
         {
-          padding: 1,
+          padding: { top: 1, bottom: 1, left: 3, right: 3 },
           margin: { top: 0, bottom: 1, left: 2, right: 2 },
           borderStyle: "round",
           borderColor: "yellow",
-          align: "left",
+          align: "center",
+          width: 40,
         }
       )
     );
@@ -91,20 +121,25 @@ export async function update(currentVersion: string): Promise<void> {
     });
 
     updateSpinner.succeed(colors.green("更新成功！"));
+
+    // 清理缓存文件
+    clearUpdateCache();
+
     console.log("");
     console.log(
       boxen(
         [
-          colors.bold("✨ 更新完成！"),
+          colors.green(colors.bold("✨ 更新完成！")),
           "",
           colors.dim("请重新打开终端使用新版本"),
         ].join("\n"),
         {
-          padding: 1,
+          padding: { top: 1, bottom: 1, left: 3, right: 3 },
           margin: { top: 0, bottom: 1, left: 2, right: 2 },
           borderStyle: "round",
           borderColor: "green",
-          align: "left",
+          align: "center",
+          width: 40,
         }
       )
     );