@lakakala/kgit 0.2.0 → 0.3.0

package/README.md

@@ -1 +1,183 @@
-# kgit
+# kgit
+
+使用 [git worktree](https://git-scm.com/docs/git-worktree) 管理多仓库工作区的 CLI 工具。
+
+## 安装
+
+```bash
+npm install -g @lakakala/kgit
+```
+
+## 配置
+
+在 `~/.config/kgit/config.json` 中创建配置文件：
+
+```json
+{
+  "workspace": "$HOME/projects",
+  "ide": "trae",
+  "projects": [
+    {
+      "name": "form",
+      "path": "$HOME/repos/ens_bpm_form"
+    },
+    {
+      "name": "auth",
+      "path": "$HOME/repos/ens_bpm_auth"
+    }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `workspace` | 工作区根目录，所有工程都创建在此目录下 |
+| `ide` | 默认编辑器（可选），支持 `code`、`trae`、`cursor`、`nvim`、`vim` 等 |
+| `projects[].name` | 项目别名，在 `-p` 参数中使用 |
+| `projects[].path` | 项目 git 仓库的绝对路径 |
+
+`workspace` 和 `path` 中均支持环境变量（`$HOME`、`$VAR`、`${VAR}`）。
+
+---
+
+## 命令
+
+### `kgit new`
+
+创建新工程，为每个项目建立 git worktree。
+
+```bash
+kgit new <工程名称> [-b <分支名>] -p <项目[:基准分支]> [-p ...]
+```
+
+**选项**
+
+| 选项 | 说明 |
+|------|------|
+| `-b <branch>` | 新分支名，默认使用工程名称 |
+| `-p <project[:base]>` | 添加项目，可选指定基准分支（默认 `master`），可重复使用 |
+
+**分支解析逻辑**（按优先级）：
+
+1. 本地已存在该分支 → 直接使用
+2. 远程存在该分支 → 创建本地追踪分支
+3. 分支不存在 → 基于 `<基准分支>` 新建
+
+**示例**
+
+```bash
+# 基于 master 创建工程 feat-login，新分支名为 feat-login
+kgit new feat-login -p form -p auth
+
+# 指定基准分支
+kgit new feat-login -p form:develop -p auth:develop
+
+# 使用 -b 指定新分支名（可复用已有本地/远程分支）
+kgit new feat-login -b my-feature -p form:develop
+
+# 多项目使用不同基准分支
+kgit new feat-login -p form:master -p auth:develop
+```
+
+**目录结构**
+
+```
+$workspace/
+└── feat-login/
+    ├── form/     ← worktree，分支 feat-login
+    └── auth/     ← worktree，分支 feat-login
+```
+
+---
+
+### `kgit append`
+
+向已有工程追加项目，选项与 `new` 相同。
+
+```bash
+kgit append <工程名称> [-b <分支名>] -p <项目[:基准分支]> [-p ...]
+```
+
+**示例**
+
+```bash
+kgit append feat-login -p gateway:master
+```
+
+---
+
+### `kgit remove`
+
+删除工程或工程中的指定项目。
+
+```bash
+kgit remove <工程名称>               # 删除整个工程
+kgit remove <工程名称> -p <项目> [-p ...]  # 删除指定项目
+```
+
+删除前会检测分支是否已推送到远程，若存在未同步的提交则需二次确认。
+
+**示例**
+
+```bash
+kgit remove feat-login           # 删除所有 worktree 及工程目录
+kgit remove feat-login -p form   # 仅删除 form 的 worktree
+```
+
+---
+
+### `kgit list`
+
+列出所有已创建的工程及其项目和当前分支。
+
+```bash
+kgit list
+```
+
+**输出示例**
+
+```
+feat-login
+  └─ form  (feat-login)
+  └─ auth  (feat-login)
+```
+
+---
+
+### `kgit edit`
+
+用指定编辑器打开项目目录。
+
+```bash
+kgit edit <工程名称> <项目名称> [--ide <编辑器>]
+```
+
+**选项**
+
+| 选项 | 说明 |
+|------|------|
+| `--ide <name>` | 指定编辑器，未传则依次读取 config.json 中的 `ide` 字段，再自动检测 |
+
+**编辑器优先级**：`--ide` 参数 → config.json `ide` 字段 → 自动检测（`code → trae → cursor → nvim → vim`）
+
+| 类型 | 支持的编辑器 |
+|------|------------|
+| GUI（后台启动） | `code`、`trae`、`cursor`、`idea`、`webstorm` |
+| 终端（前台运行） | `nvim`、`vim`、`vi`、`nano` |
+
+**示例**
+
+```bash
+kgit edit feat-login form
+kgit edit feat-login form --ide nvim
+```
+
+---
+
+### `kgit version`
+
+打印当前版本号。
+
+```bash
+kgit version
+```

package/dist/commands/edit.d.ts

@@ -0,0 +1,3 @@
+export declare function editCommand(workspaceName: string, projectName: string, options: {
+    ide?: string;
+}): Promise<void>;

package/dist/commands/edit.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { execa } from 'execa';
+import { loadConfig } from '../config.js';
+const IDE_COMMANDS = {
+    code: 'code',
+    trae: 'trae',
+    cursor: 'cursor',
+    nvim: 'nvim',
+    vim: 'vim',
+    vi: 'vi',
+    nano: 'nano',
+    idea: 'idea',
+    webstorm: 'webstorm',
+};
+const TERMINAL_IDES = new Set(['nvim', 'vim', 'vi', 'nano']);
+async function detectDefaultIde() {
+    for (const cmd of ['code', 'trae', 'cursor', 'nvim', 'vim']) {
+        try {
+            await execa('which', [cmd], { stdio: 'pipe' });
+            return cmd;
+        }
+        catch {
+            // not found, try next
+        }
+    }
+    return null;
+}
+export async function editCommand(workspaceName, projectName, options) {
+    const config = loadConfig();
+    const worktreePath = path.join(config.workspace, workspaceName, projectName);
+    if (!fs.existsSync(worktreePath)) {
+        throw new Error(`Project path does not exist: ${worktreePath}`);
+    }
+    let ideName = options.ide?.toLowerCase()
+        ?? config.ide?.toLowerCase();
+    if (!ideName) {
+        const detected = await detectDefaultIde();
+        if (!detected) {
+            throw new Error('No IDE detected. Please specify one with --ide or set "ide" in config.');
+        }
+        ideName = detected;
+        console.log(`Using detected IDE: ${ideName}`);
+    }
+    const command = IDE_COMMANDS[ideName] ?? ideName;
+    console.log(`Opening ${worktreePath} with ${command}...`);
+    if (TERMINAL_IDES.has(ideName)) {
+        await execa(command, [worktreePath], { stdio: 'inherit' });
+    }
+    else {
+        execa(command, [worktreePath], { detached: true, stdio: 'ignore' }).unref();
+    }
+}

package/dist/commands/remove.js

@@ -1,7 +1,30 @@
 import path from 'node:path';
 import fs from 'node:fs';
+import readline from 'node:readline';
 import { loadConfig, findProject } from '../config.js';
-import { removeWorktree } from '../git.js';
+import { removeWorktree, isBranchSyncedToRemote } from '../git.js';
+function confirm(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+        rl.question(`${question} (y/N) `, answer => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}
+async function checkAndRemove(repoPath, worktreePath, projectName) {
+    const synced = await isBranchSyncedToRemote(worktreePath);
+    if (!synced) {
+        console.warn(`  Warning: "${projectName}" has unpushed commits or no remote tracking branch.`);
+        const ok = await confirm(`  Remove worktree "${projectName}" anyway?`);
+        if (!ok) {
+            console.log(`  Skipped "${projectName}".`);
+            return;
+        }
+    }
+    console.log(`Removing worktree "${projectName}" from ${repoPath}`);
+    await removeWorktree(repoPath, worktreePath);
+}
 export async function removeCommand(workspaceName, projectEntries) {
     const config = loadConfig();
     const targetDir = path.join(config.workspace, workspaceName);
@@ -9,18 +32,21 @@ export async function removeCommand(workspaceName, projectEntries) {
         throw new Error(`Workspace directory does not exist: ${targetDir}`);
     }
     if (projectEntries.length === 0) {
-        // Remove entire workspace: prune all worktrees then delete folder
         const entries = fs.readdirSync(targetDir);
         for (const entry of entries) {
             const worktreePath = path.join(targetDir, entry);
             const project = config.projects.find(p => p.name === entry);
             if (project && fs.statSync(worktreePath).isDirectory()) {
-                console.log(`Removing worktree "${entry}" from ${project.path}`);
-                await removeWorktree(project.path, worktreePath);
+                await checkAndRemove(project.path, worktreePath, entry);
             }
         }
-        fs.rmSync(targetDir, { recursive: true, force: true });
-        console.log(`Workspace "${workspaceName}" removed.`);
+        if (fs.readdirSync(targetDir).length === 0) {
+            fs.rmSync(targetDir, { recursive: true, force: true });
+            console.log(`Workspace "${workspaceName}" removed.`);
+        }
+        else {
+            console.log(`Workspace "${workspaceName}" partially removed (some projects were skipped).`);
+        }
     }
     else {
         for (const entry of projectEntries) {
@@ -30,10 +56,8 @@ export async function removeCommand(workspaceName, projectEntries) {
                 console.warn(`Worktree not found, skipping: ${worktreePath}`);
                 continue;
             }
-            console.log(`Removing worktree "${project.name}" from ${project.path}`);
-            await removeWorktree(project.path, worktreePath);
+            await checkAndRemove(project.path, worktreePath, project.name);
         }
-        // Remove workspace dir if now empty
         if (fs.readdirSync(targetDir).length === 0) {
             fs.rmdirSync(targetDir);
             console.log(`Workspace directory is now empty and has been removed.`);

package/dist/config.d.ts

@@ -21,18 +21,21 @@ declare const ConfigSchema: z.ZodObject<{
         name: string;
         path: string;
     }>, "many">;
+    ide: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     workspace: string;
     projects: {
         name: string;
         path: string;
     }[];
+    ide?: string | undefined;
 }, {
     workspace: string;
     projects: {
         name: string;
         path: string;
     }[];
+    ide?: string | undefined;
 }>;
 export type Project = z.infer<typeof ProjectSchema>;
 export type Config = z.infer<typeof ConfigSchema>;

package/dist/config.js

@@ -10,6 +10,7 @@ const ProjectSchema = z.object({
 const ConfigSchema = z.object({
     workspace: z.string(),
     projects: z.array(ProjectSchema),
+    ide: z.string().optional(),
 });
 function expandEnvVars(value) {
     return value.replace(/\$([A-Z_][A-Z0-9_]*)/g, (_, name) => {

package/dist/git.d.ts

@@ -1,3 +1,4 @@
 export declare function addWorktree(repoPath: string, worktreePath: string, newBranch: string, baseBranch: string): Promise<void>;
+export declare function isBranchSyncedToRemote(worktreePath: string): Promise<boolean>;
 export declare function removeWorktree(repoPath: string, worktreePath: string): Promise<void>;
 export declare function isGitRepo(dirPath: string): Promise<boolean>;

package/dist/git.js

@@ -33,6 +33,19 @@ export async function addWorktree(repoPath, worktreePath, newBranch, baseBranch)
     // Branch does not exist — create from base branch
     await execa('git', ['-C', repoPath, 'worktree', 'add', '-b', newBranch, worktreePath, baseBranch], { stdio: 'inherit' });
 }
+export async function isBranchSyncedToRemote(worktreePath) {
+    try {
+        // Check if there is an upstream tracking branch
+        await execa('git', ['-C', worktreePath, 'rev-parse', '--abbrev-ref', '@{u}'], { stdio: 'pipe' });
+    }
+    catch {
+        // No upstream configured — treat as unsynced
+        return false;
+    }
+    // Check for commits not yet pushed to upstream
+    const { stdout } = await execa('git', ['-C', worktreePath, 'rev-list', '--count', '@{u}..HEAD'], { stdio: 'pipe' });
+    return parseInt(stdout.trim(), 10) === 0;
+}
 export async function removeWorktree(repoPath, worktreePath) {
     await execa('git', ['-C', repoPath, 'worktree', 'remove', worktreePath, '--force'], {
         stdio: 'inherit',

package/dist/index.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { createRequire } from 'node:module';
 import { newCommand } from './commands/new.js';
 import { appendCommand } from './commands/append.js';
 import { removeCommand } from './commands/remove.js';
 import { listCommand } from './commands/list.js';
+import { editCommand } from './commands/edit.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
 function collectProject(value, previous) {
     const colonIdx = value.indexOf(':');
     const name = colonIdx === -1 ? value : value.slice(0, colonIdx);
@@ -14,7 +18,7 @@ const program = new Command();
 program
     .name('kgit')
     .description('Git worktree workspace manager')
-    .version('0.1.0');
+    .version(version);
 program
     .command('new <workspace>')
     .description('Create a new workspace with git worktrees')
@@ -52,6 +56,19 @@ program
     .action(async () => {
     await listCommand();
 });
+program
+    .command('edit <workspace> <project>')
+    .description('Open a project worktree in an IDE or editor')
+    .option('--ide <name>', 'Editor to use: code, trae, cursor, nvim, vim, etc.')
+    .action(async (workspace, project, options) => {
+    await editCommand(workspace, project, options);
+});
+program
+    .command('version')
+    .description('Print the current version')
+    .action(() => {
+    console.log(`kgit v${version}`);
+});
 program.parseAsync(process.argv, { from: 'node' }).catch((err) => {
     console.error(`Error: ${err.message}`);
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lakakala/kgit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Git worktree workspace manager",
   "type": "module",
   "bin": {