repo-do 1.3.1 → 1.3.2

package/README.md

@@ -6,7 +6,7 @@ A unified CLI tool for managing git repositories with a structured directory lay
 Organize all your repositories in a consistent domain-based structure.
 Fast search, clipboard integration, and cross-platform support.
 
-English · [简体中文](./docs/README.zh-CN.md)
+English · [简体中文](https://github.com/STDSuperman/node-utils/blob/master/packages/repo-do/docs/README.zh-CN.md)
 
 [![npm version](https://img.shields.io/npm/v/repo-do.svg?style=flat-square)](https://www.npmjs.com/package/repo-do)
 [![license](https://img.shields.io/npm/l/repo-do.svg?style=flat-square)](https://github.com/STDSuperman/repo-do/blob/master/LICENSE)
@@ -36,14 +36,14 @@ English · [简体中文](./docs/README.zh-CN.md)
 npm install -g repo-do
 ```
 
-> **Tip**: After installation, you can use the shorter command `rpd` instead of `repo-do` for faster typing!
+> **Command aliases**: `rpd` and `repo-do` are equivalent. The examples below prefer the shorter `rpd` alias.
 
 ## Quick Start
 
 ### 1. Initialize Configuration
 
 ```bash
-repo-do init
+rpd init
 ```
 
 This prompts you to set a base directory for storing repositories (default: `~/.repo-do/repo`).
@@ -51,7 +51,7 @@ This prompts you to set a base directory for storing repositories (default: `~/.
 ### 2. Clone a Repository
 
 ```bash
-repo-do add git@github.com:STDSuperman/super-image-cropper.git
+rpd add git@github.com:STDSuperman/super-image-cropper.git
 ```
 
 The repository will be cloned to:
@@ -64,7 +64,7 @@ The `cd` command is automatically copied to your clipboard!
 ### 3. Find a Repository
 
 ```bash
-repo-do find super-image
+rpd find super-image
 ```
 
 Output:
@@ -76,7 +76,7 @@ Found 1 repository:
 ### 4. List All Repositories
 
 ```bash
-repo-do list
+rpd list
 ```
 
 Output:
@@ -90,15 +90,15 @@ Total: 3 repositories
 
 ## Commands
 
-### `repo-do init`
+### `rpd init` / `repo-do init`
 
 Initialize configuration and set the base directory for repositories.
 
 ```bash
-repo-do init
+rpd init
 ```
 
-### `repo-do add <repo_url> [git-clone-args...]`
+### `rpd add <repo_url> [git-clone-args...]` / `repo-do add <repo_url> [git-clone-args...]`
 
 Clone a repository to the structured directory.
 
@@ -110,25 +110,25 @@ Clone a repository to the structured directory.
 
 ```bash
 # Basic clone
-repo-do add git@github.com:STDSuperman/super-image-cropper.git
+rpd add git@github.com:STDSuperman/super-image-cropper.git
 
 # Shallow clone
-repo-do add https://github.com/STDSuperman/super-image-cropper.git --depth 1
+rpd add https://github.com/STDSuperman/super-image-cropper.git --depth 1
 
 # Clone specific branch
-repo-do add https://github.com/STDSuperman/super-image-cropper.git --branch develop
+rpd add https://github.com/STDSuperman/super-image-cropper.git --branch develop
 
 # SSH clone
-repo-do add git@github.com:STDSuperman/NanoBanana-PPT-Skills.git
+rpd add git@github.com:STDSuperman/NanoBanana-PPT-Skills.git
 
 # JSON output (for scripts and AI models)
-repo-do add https://github.com/user/repo.git --json
+rpd add https://github.com/user/repo.git --json
 
 # Force a new clone even if the same remote is already tracked
-repo-do add https://github.com/user/repo.git --force-clone
+rpd add https://github.com/user/repo.git --force-clone
 
 # Use an already tracked local repository without prompting
-repo-do add https://github.com/user/repo.git --use-existing
+rpd add https://github.com/user/repo.git --use-existing
 ```
 
 Before cloning, `repo-do` checks the global repository configuration for the same remote repository. SSH and HTTPS remotes such as `git@github.com:user/repo.git` and `https://github.com/user/repo` are treated as the same repository. If a matching repository already exists in another local directory, interactive mode asks whether to use the existing directory. `--json` mode uses the existing directory automatically unless `--force-clone` is provided.
@@ -166,14 +166,14 @@ On failure, the process exits with code 1 and outputs:
         └── internal-tool/
 ```
 
-### `repo-do find <query>`
+### `rpd find <query>` / `repo-do find <query>`
 
 Search for repositories by name, group, or path fragment (case-insensitive).
 
 ```bash
-repo-do find super-image
-repo-do find STDSuperman
-repo-do find github.com
+rpd find super-image
+rpd find STDSuperman
+rpd find github.com
 ```
 
 **Output format:**
@@ -185,57 +185,57 @@ Found 2 repositories:
 
 Each result is prefixed with a number, followed by the absolute path.
 
-### `repo-do list [--refresh]`
+### `rpd list [--refresh]` / `repo-do list [--refresh]`
 
 List all managed repositories.
 
 ```bash
 # List from cache (fast)
-repo-do list
+rpd list
 
 # Force rebuild cache
-repo-do list --refresh
+rpd list --refresh
 ```
 
 When `--refresh` is used, `repo-do` scans the configured base directory, records detected Git repositories in configuration, and rebuilds the fast repository cache.
 
-### `repo-do scan [paths...]`
+### `rpd scan [paths...]` / `repo-do scan [paths...]`
 
 Scan existing Git repositories and track them in configuration.
 
 ```bash
 # Scan the configured base directory
-repo-do scan
+rpd scan
 
 # Scan one or more custom directories
-repo-do scan ~/Code ~/work
+rpd scan ~/Code ~/work
 ```
 
 Detected repositories are grouped by normalized remote URL. If the same remote exists in multiple local directories, all directories are stored as locations for that repository.
 
-### `repo-do remove <repo>`
+### `rpd remove <repo>` / `repo-do remove <repo>`
 
 Remove a repository from tracking (does not delete files).
 
 ```bash
-repo-do remove super-image
+rpd remove super-image
 ```
 
 If multiple matches are found, you'll be prompted to select which one to remove.
 
-### `repo-do config [options]`
+### `rpd config [options]` / `repo-do config [options]`
 
 View or modify configuration.
 
 ```bash
 # Show current config
-repo-do config
+rpd config
 
 # Get base directory
-repo-do config --get baseDirectory
+rpd config --get baseDirectory
 
 # Set base directory
-repo-do config --set baseDirectory /path/to/repos
+rpd config --set baseDirectory /path/to/repos
 ```
 
 ## Directory Structure
@@ -291,9 +291,9 @@ Configuration is stored in `~/.repo-do/config.json`:
 To improve performance, `repo-do` maintains a repository cache at `~/.repo-do/repo_cache.json`.
 
 **Cache is automatically updated when:**
-- Adding a new repository (`repo-do add`)
-- Removing a repository (`repo-do remove`)
-- Forcing refresh (`repo-do list --refresh`)
+- Adding a new repository (`rpd add` / `repo-do add`)
+- Removing a repository (`rpd remove` / `repo-do remove`)
+- Forcing refresh (`rpd list --refresh` / `repo-do list --refresh`)
 
 **Cache format:**
 ```json

package/docs/README.zh-CN.md

@@ -0,0 +1,403 @@
+<div align="center">
+
+# repo-do
+
+一个用于统一管理 Git 仓库的 CLI 工具，提供结构化的目录布局。
+以一致的、基于域名的结构组织你的所有仓库。
+快速搜索、剪贴板集成、跨平台支持。
+
+[English](https://github.com/STDSuperman/node-utils/blob/master/packages/repo-do/README.md) · 简体中文
+
+[![npm 版本](https://img.shields.io/npm/v/repo-do.svg?style=flat-square)](https://www.npmjs.com/package/repo-do)
+[![许可证](https://img.shields.io/npm/l/repo-do.svg?style=flat-square)](https://github.com/STDSuperman/repo-do/blob/master/LICENSE)
+[![Node.js 版本](https://img.shields.io/node/v/repo-do.svg?style=flat-square)](https://nodejs.org)
+[![下载量](https://img.shields.io/npm/dm/repo-do.svg?style=flat-square)](https://www.npmjs.com/package/repo-do)
+
+</div>
+
+## 概述
+
+`repo-do` 帮助你以统一的、基于域名的目录结构组织所有 Git 仓库。它会自动将仓库克隆到规范的路径下，并提供快速搜索功能，让你轻松查找和访问项目。
+
+## 特性
+
+- **结构化组织**：按 `{baseDir}/{domain}/{group}/{repo}` 结构克隆仓库
+- **快速仓库搜索**：通过名称或路径片段快速查找仓库
+- **剪贴板集成**：自动复制 `cd` 命令到剪贴板
+- **缓存性能优化**：快速列出仓库，无需重复扫描目录
+- **跨平台支持**：支持 Windows、macOS 和 Linux
+- **Git 参数透传**：支持所有 git clone 参数（--depth、--branch 等）
+
+## 安装
+
+```bash
+npm install -g repo-do
+```
+
+> **命令别名**：`rpd` 和 `repo-do` 等价。下面的示例优先使用更短的 `rpd`。
+
+## 快速开始
+
+### 1. 初始化配置
+
+```bash
+rpd init
+```
+
+这将提示你设置存储仓库的基础目录（默认：`~/.repo-do/repo`）。
+
+### 2. 克隆仓库
+
+```bash
+rpd add git@github.com:STDSuperman/super-image-cropper.git
+```
+
+仓库将被克隆到：
+```
+{baseDir}/github.com/STDSuperman/super-image-cropper
+```
+
+`cd` 命令会自动复制到剪贴板！
+
+### 3. 查找仓库
+
+```bash
+rpd find super-image
+```
+
+输出：
+```
+找到 1 个仓库:
+1. D:\Code\github.com\STDSuperman\super-image-cropper
+```
+
+### 4. 列出所有仓库
+
+```bash
+rpd list
+```
+
+输出：
+```
+github.com/STDSuperman/super-image-cropper
+github.com/STDSuperman/NanoBanana-PPT-Skills
+gitlab.com/myorg/internal-tool
+
+总计: 3 个仓库
+```
+
+## 命令
+
+### `rpd init` / `repo-do init`
+
+初始化配置并设置仓库的基础目录。
+
+```bash
+rpd init
+```
+
+### `rpd add <repo_url> [git-clone-args...]` / `repo-do add <repo_url> [git-clone-args...]`
+
+克隆仓库到结构化目录。
+
+**支持的 URL 格式：**
+- HTTPS：`https://github.com/user/repo.git` 或 `https://github.com/user/repo`
+- SSH：`git@github.com:user/repo.git` 或 `ssh://git@github.com/user/repo.git`
+
+**示例：**
+
+```bash
+# 基础克隆
+rpd add git@github.com:STDSuperman/super-image-cropper.git
+
+# 浅克隆
+rpd add https://github.com/STDSuperman/super-image-cropper.git --depth 1
+
+# 克隆指定分支
+rpd add https://github.com/STDSuperman/super-image-cropper.git --branch develop
+
+# SSH 克隆
+rpd add git@github.com:STDSuperman/NanoBanana-PPT-Skills.git
+
+# JSON 输出（供脚本和 AI 模型使用）
+rpd add https://github.com/user/repo.git --json
+
+# 即使同一个远端仓库已被记录，也强制克隆一份新的
+rpd add https://github.com/user/repo.git --force-clone
+
+# 不询问，直接采用已记录的本地仓库
+rpd add https://github.com/user/repo.git --use-existing
+```
+
+克隆前，`repo-do` 会先查询全局仓库配置。`git@github.com:user/repo.git` 和 `https://github.com/user/repo` 这类 SSH/HTTPS 地址会被识别为同一个远端仓库。如果同一个远端已经存在于其他本地目录，交互模式会询问是否直接采用已有目录；`--json` 模式默认直接采用已有目录，除非传入 `--force-clone`。
+
+**`--json` 输出：**
+
+使用 `--json` 时，命令仅在 stdout 输出一行 JSON，不会有 spinner、颜色或剪贴板操作：
+
+```json
+{"success":true,"path":"/path/to/repo","alreadyExists":false,"message":""}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | boolean | `true` 表示仓库路径可用（已克隆或已存在） |
+| `path` | string | 本地仓库的绝对路径 |
+| `alreadyExists` | boolean | `true` 表示仓库此前已克隆过 |
+| `adoptedExisting` | boolean | `true` 表示采用了其他目录里的已有仓库 |
+| `message` | string | 错误或状态信息 |
+
+失败时进程以 exit code 1 退出，输出：
+```json
+{"success":false,"path":"","alreadyExists":false,"message":"错误详情"}
+```
+
+**目录结构：**
+```
+{baseDir}/
+├── github.com/
+│   └── STDSuperman/
+│       ├── super-image-cropper/
+│       └── NanoBanana-PPT-Skills/
+└── gitlab.com/
+    └── myorg/
+        └── internal-tool/
+```
+
+### `rpd find <query>` / `repo-do find <query>`
+
+通过名称、组织或路径片段搜索仓库（不区分大小写）。
+
+```bash
+rpd find super-image
+rpd find STDSuperman
+rpd find github.com
+```
+
+**输出格式：**
+```
+找到 2 个仓库:
+1. D:\Code\github.com\STDSuperman\super-image-cropper
+2. D:\Code\github.com\STDSuperman\NanoBanana-PPT-Skills
+```
+
+每个结果前都有序号，后面是仓库的绝对路径。
+
+### `rpd list [--refresh]` / `repo-do list [--refresh]`
+
+列出所有管理的仓库。
+
+```bash
+# 从缓存列出（快速）
+rpd list
+
+# 强制重建缓存
+rpd list --refresh
+```
+
+使用 `--refresh` 时，`repo-do` 会扫描已配置的基础目录，将检测到的 Git 仓库写入配置，并重建快速缓存。
+
+### `rpd scan [paths...]` / `repo-do scan [paths...]`
+
+扫描已有 Git 仓库并写入配置。
+
+```bash
+# 扫描配置里的基础目录
+rpd scan
+
+# 扫描一个或多个自定义目录
+rpd scan ~/Code ~/work
+```
+
+扫描到的仓库会按规范化后的远端地址归档。如果同一个远端仓库存在多份本地目录，这些目录会作为同一个仓库的多个 location 维护。
+
+### `rpd remove <repo>` / `repo-do remove <repo>`
+
+从追踪中移除仓库（不会删除文件）。
+
+```bash
+rpd remove super-image
+```
+
+如果找到多个匹配项，会提示你选择要移除的仓库。
+
+### `rpd config [options]` / `repo-do config [options]`
+
+查看或修改配置。
+
+```bash
+# 显示当前配置
+rpd config
+
+# 获取基础目录
+rpd config --get baseDirectory
+
+# 设置基础目录
+rpd config --set baseDirectory /path/to/repos
+```
+
+## 目录结构
+
+所有仓库都按统一结构组织：
+
+```
+{baseDirectory}/{domain}/{group}/{repository}
+```
+
+**示例：**
+
+| Git URL | 克隆路径 |
+|---------|---------|
+| `git@github.com:STDSuperman/super-image-cropper.git` | `{baseDir}/github.com/STDSuperman/super-image-cropper` |
+| `git@gitlab.com:myorg/myrepo.git` | `{baseDir}/gitlab.com/myorg/myrepo` |
+| `https://github.com/STDSuperman/NanoBanana-PPT-Skills.git` | `{baseDir}/github.com/STDSuperman/NanoBanana-PPT-Skills` |
+
+## 配置
+
+配置存储在 `~/.repo-do/config.json`：
+
+```json
+{
+  "baseDirectory": "D:\\Code",
+  "version": "1.0.0",
+  "repositories": [
+    {
+      "id": "github.com/STDSuperman/super-image-cropper",
+      "canonicalRemote": "github.com/STDSuperman/super-image-cropper",
+      "displayUrl": "git@github.com:STDSuperman/super-image-cropper.git",
+      "domain": "github.com",
+      "group": "STDSuperman",
+      "name": "super-image-cropper",
+      "preferredPath": "D:\\Code\\github.com\\STDSuperman\\super-image-cropper",
+      "locations": [
+        {
+          "path": "D:\\Code\\github.com\\STDSuperman\\super-image-cropper",
+          "remoteUrl": "git@github.com:STDSuperman/super-image-cropper.git",
+          "remoteName": "origin",
+          "source": "clone",
+          "firstSeenAt": "2026-01-11T12:00:00.000Z",
+          "lastSeenAt": "2026-01-11T12:00:00.000Z"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 缓存系统
+
+为了提高性能，`repo-do` 在 `~/.repo-do/repo_cache.json` 维护了一个仓库缓存。
+
+**缓存会在以下情况自动更新：**
+- 添加新仓库（`rpd add` / `repo-do add`）
+- 移除仓库（`rpd remove` / `repo-do remove`）
+- 强制刷新（`rpd list --refresh` / `repo-do list --refresh`）
+
+**缓存格式：**
+```json
+{
+  "repositories": [
+    {
+      "name": "super-image-cropper",
+      "fullPath": "D:\\Code\\github.com\\STDSuperman\\super-image-cropper",
+      "gitUrl": "git@github.com:STDSuperman/super-image-cropper.git",
+      "domain": "github.com",
+      "group": "STDSuperman",
+      "lastUpdated": "2026-01-11T12:00:00.000Z"
+    }
+  ],
+  "lastUpdated": "2026-01-11T12:00:00.000Z"
+}
+```
+
+## 跨平台支持
+
+### 剪贴板支持
+
+- **macOS**：使用 `pbcopy`
+- **Linux**：使用 `xclip` 或 `xsel`（可能需要安装）
+- **Windows**：使用 `clip` 命令
+
+如果剪贴板操作失败，路径仍会显示在终端中。
+
+### 路径处理
+
+所有路径都使用 Node.js `path` 模块处理，确保跨平台兼容性。
+
+## 系统要求
+
+- Node.js >= 18.0.0
+- 已安装 Git 并在 PATH 中可用
+
+## 错误处理
+
+`repo-do` 为常见问题提供清晰的错误消息：
+
+- **INVALID_URL**：无法识别的 Git URL 格式
+- **CLONE_FAILED**：Git 克隆操作失败
+- **CONFIG_ERROR**：配置文件读写错误
+- **NOT_FOUND**：在缓存中未找到仓库
+- **PERMISSION_DENIED**：文件系统权限错误
+- **GIT_NOT_INSTALLED**：未安装 Git
+- **PATH_CONFLICT**：目标路径已存在，但不是请求的仓库
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/your-username/repo-do.git
+cd repo-do
+
+# 安装依赖
+npm install
+
+# 开发模式运行
+npm run dev
+
+# 构建
+npm run build
+
+# 运行测试
+npm test
+```
+
+## 项目结构
+
+```
+repo-do/
+├── src/
+│   ├── commands/        # CLI 命令实现
+│   ├── core/            # 核心业务逻辑
+│   ├── utils/           # 工具函数
+│   ├── types/           # TypeScript 类型定义
+│   ├── constants/       # 常量
+│   └── index.ts         # CLI 入口
+├── bin/
+│   └── repo-do.js         # 可执行文件入口
+├── dist/                # 编译输出
+└── tests/               # 测试文件
+```
+
+## 依赖说明
+
+- **chalk**：终端文本样式
+- **clipboardy**：跨平台剪贴板操作
+- **commander**：CLI 框架
+- **inquirer**：交互式命令行提示
+- **ora**：优雅的终端 spinner
+
+## 开源协议
+
+MIT
+
+## 贡献
+
+欢迎贡献！请随时提交 Pull Request。
+
+## 更新日志
+
+### 1.0.0
+- 初始版本发布
+- 核心功能：init、add、list、find、remove、config
+- 跨平台支持
+- 缓存系统实现快速仓库列表

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-do",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Unified git repository management tool",
   "main": "dist/index.js",
   "type": "module",
@@ -22,6 +22,7 @@
   "files": [
     "dist",
     "bin",
+    "docs",
     "README.md",
     "LICENSE"
   ],