easy-command 1.0.4 → 2.0.2

package/README.md

@@ -1,109 +1,106 @@
-# easy-command
-
-One command to configure a polished Zsh terminal with Oh My Zsh, the `agnoster` theme, Git status, command suggestions, Tab completion, and syntax highlighting.
-
-> 一条命令配置统一的 Zsh 终端：Oh My Zsh、`agnoster` 主题、Git 状态、历史命令建议、Tab 补全与命令语法高亮。
+<p align="right">
+  <strong>ENGLISH</strong> | <a href="README_CN.md">中文</a>
+</p>
 
-## Preview
+# easy-command
 
-> 效果预览。
+Configure a polished Zsh terminal in one command.
 
-### Git branch and working-tree status
+`easy-command` installs and configures Oh My Zsh, the `agnoster` theme, Git status, command suggestions, Tab completion, and syntax highlighting. It preserves your existing `.zshrc` content and creates a backup before every change.
 
-> Git 分支与工作区状态。
+## INSTALL
 
-![agnoster displays Git branch and working-tree status](assets/git-status.png)
+### npm
 
-### History-based command suggestions
+```bash
+npx easy-command -y
+```
 
-> 历史命令自动建议。
+### GitHub
 
-![A suggested history command appears while typing](assets/autosuggestions.png)
+No Node.js or npm is required:
 
-### Syntax highlighting and error feedback
+```bash
+curl -fsSL https://raw.githubusercontent.com/UnionSchool/easy-command/main/install.sh | bash -s -- -y
+```
 
-> 命令语法高亮与错误提示。
+When installation finishes, open a new terminal session or run:
 
-![Valid commands are green and unknown commands are red](assets/syntax-highlighting.png)
+```bash
+exec zsh -l
+```
 
-## Quick start
+## Everyday commands
 
-> 快速开始。
+```bash
+# Preview installation without changing your machine
+npx easy-command --dry-run
 
-Install the latest version:
+# Check Shell, dependencies, managed repositories, and .zshrc configuration
+npx easy-command doctor
 
-> 安装最新版本：
+# Restore missing managed files and configuration
+npx easy-command repair -y
 
-```bash
-npx easy-command --yes
+# Safely update Oh My Zsh and managed plugins
+npx easy-command update -y
 ```
 
-Or install directly from GitHub without Node.js/npm:
+`npx` runs the command without a global npm installation. If you prefer the shorter `easy-command` command, install it globally with `npm install -g easy-command`.
 
-> 或者无需 Node.js/npm，直接从 GitHub 安装：
+## What you get
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/UnionSchool/easy-command/main/install.sh | bash -s -- --yes
-```
+- A clean `agnoster` prompt with your user, path, Git branch, and working-tree status.
+- History-based command suggestions. Press `→` or `Ctrl+E` to accept one.
+- Syntax highlighting: valid commands are green; unknown commands are bold red.
+- Native Zsh completion. Press `Tab` to complete; press it twice to view candidates.
+- Shared history across terminal sessions, retaining the latest 10,000 commands.
+- Built-in preview, diagnostics, repair, and update commands for easy maintenance.
 
-After installation, sign in again or run:
+## Preview
 
-> 安装完成后重新登录，或运行：
+### Git branch and working-tree status
 
-```bash
-exec zsh -l
-```
+![agnoster displays Git branch and working-tree status](assets/git-status.png)
 
-## What you get
+### History-based command suggestions
 
-> 提供的能力。
+![A suggested history command appears while typing](assets/autosuggestions.png)
 
-- `agnoster`: shows the user, current path, Git branch, and working-tree status.<br>
-  `agnoster`：显示用户名、路径、Git 分支和工作区状态。
-- `zsh-autosuggestions`: shows gray suggestions from command history; press `→` or `Ctrl+E` to accept.<br>
-  `zsh-autosuggestions`：从历史命令显示灰色建议，按 `→` 或 `Ctrl+E` 接受。
-- `zsh-syntax-highlighting`: valid commands are green; unknown commands are bold red.<br>
-  `zsh-syntax-highlighting`：有效命令绿色、未知命令红色加粗。
-- Native Zsh completion: press `Tab` to complete commands, paths, and Git subcommands; press it twice for candidates.<br>
-  Zsh 原生补全：按 `Tab` 补全命令、路径和 Git 子命令，连按两次显示候选项。
-- Shared history: the latest 10,000 commands are shared between terminal sessions.<br>
-  共享历史：多个终端会话共享最近 10,000 条命令。
+### Syntax highlighting and error feedback
 
-## Options
+![Valid commands are green and unknown commands are red](assets/syntax-highlighting.png)
 
-> 参数。
+## Options
 
 ```bash
-# Configure a specific user / 指定目标用户
-bash install.sh --yes --user bell
+# Configure a specific user
+bash install.sh -y --user bell
 
-# Keep the current login shell / 不改变默认登录 Shell
-bash install.sh --yes --no-chsh
+# Keep the current login shell
+bash install.sh -y --no-chsh
 
-# Remove only the configuration block managed by easy-command / 删除本工具管理的 .zshrc 区块
+# Remove only the configuration block managed by easy-command
 bash install.sh --uninstall
+
+# Enable optional directory jumping, fuzzy search, and Git aliases
+bash install.sh -y --with-zoxide --with-fzf --with-git-aliases
 ```
 
-## Supported platforms
+`zoxide` enables `z <keyword>` directory jumping. `fzf` adds fuzzy history and file searching. Git aliases use the non-conflicting `ec-` prefix, such as `git ec-status`; existing aliases are never overwritten.
 
-> 支持范围。
+## Requirements
 
-- macOS: Homebrew must already be installed.<br>
-  macOS：要求已安装 Homebrew。
-- Ubuntu / Debian: dependencies are installed with `apt-get`.<br>
-  Ubuntu / Debian：使用 `apt-get` 安装依赖。
+- macOS: Homebrew must already be installed.
+- Ubuntu / Debian: dependencies are installed with `apt-get`.
 
 The script needs `sudo` to install packages and change the default shell. Without sudo access, use `--no-chsh` and have an administrator install Zsh first.
 
-> 脚本需要 `sudo` 来安装软件包和切换默认 Shell。没有 sudo 权限时，可加 `--no-chsh`，并由管理员预先安装 Zsh。
-
 ## Configuration and rollback
 
-> 配置与回退。
-
-Installed files:
+The installer manages only the marked `easy-command` block in `~/.zshrc`. Before each update, it creates a timestamped backup. Running `--uninstall` removes only that managed block; it does not remove Oh My Zsh, plugins, command history, or other personal settings.
 
-> 安装内容位于：
+Installed components:
 
 ```text
 ~/.easy-command/oh-my-zsh
@@ -111,38 +108,26 @@ Installed files:
 ~/.zsh_history
 ```
 
-Before each `.zshrc` update, the script creates a timestamped backup. `--uninstall` removes only the configuration block managed by easy-command; it does not remove Oh My Zsh, plugins, or other user settings.
-
-> 每次更新 `.zshrc` 前，脚本会创建带时间戳的备份。`--uninstall` 只删除由 easy-command 管理的配置块，不会删除 Oh My Zsh、插件或用户自己的其他配置。
-
 ## Security
 
-> 安全说明。
-
 For a first-time trial, download and inspect the script before running it:
 
-> 首次试用建议先下载并审阅脚本：
-
 ```bash
 curl -fsSLO https://raw.githubusercontent.com/UnionSchool/easy-command/main/install.sh
 less install.sh
-bash install.sh --yes
+bash install.sh -y
 ```
 
 For production, pin a release tag instead of running `main` directly:
 
-> 生产环境建议固定到发布标签，而不是直接使用 `main`：
-
 ```bash
-npx easy-command@1.0.4 --yes
+npx easy-command@2.0.2 -y
 ```
 
 Or, without npm:
 
-> 或者不使用 npm：
-
 ```bash
-curl -fsSL https://raw.githubusercontent.com/UnionSchool/easy-command/v1.0.4/install.sh | bash -s -- --yes
+curl -fsSL https://raw.githubusercontent.com/UnionSchool/easy-command/v2.0.2/install.sh | bash -s -- -y
 ```
 
 ## License

package/README_CN.md

@@ -0,0 +1,135 @@
+<p align="right">
+  <a href="README.md">ENGLISH</a> | <strong>中文</strong>
+</p>
+
+# easy-command
+
+一条命令配置更顺手的 Zsh 终端。
+
+`easy-command` 会安装并配置 Oh My Zsh、`agnoster` 主题、Git 状态、命令建议、Tab 补全和语法高亮。每次修改 `.zshrc` 前都会备份，并保留用户已有的配置内容。
+
+## 安装
+
+### npm 安装
+
+```bash
+npx easy-command -y
+```
+
+### GitHub 安装
+
+无需安装 Node.js 或 npm：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/UnionSchool/easy-command/main/install.sh | bash -s -- -y
+```
+
+安装完成后，重新打开终端，或执行：
+
+```bash
+exec zsh -l
+```
+
+## 日常命令
+
+```bash
+# 预览安装过程，不修改本机环境
+npx easy-command --dry-run
+
+# 检查 Shell、依赖、托管仓库和 .zshrc 配置
+npx easy-command doctor
+
+# 恢复缺失的托管文件和配置
+npx easy-command repair -y
+
+# 安全更新 Oh My Zsh 和托管插件
+npx easy-command update -y
+```
+
+`npx` 无需全局安装即可运行命令。若希望直接使用更短的 `easy-command` 命令，可执行 `npm install -g easy-command`。
+
+## 安装后即可使用
+
+- `agnoster` 提示符：显示用户名、当前路径、Git 分支和工作区状态。
+- 历史命令建议：输入时显示灰色建议，按 `→` 或 `Ctrl+E` 接受。
+- 语法高亮：有效命令为绿色，未知命令为红色加粗。
+- 原生 Zsh 补全：按 `Tab` 补全命令、路径和 Git 子命令；连按两次显示候选项。
+- 多终端共享历史：保留最近 10,000 条命令。
+- 内置预览、诊断、修复和更新命令，后续维护更简单。
+
+## 效果预览
+
+### Git 分支与工作区状态
+
+![agnoster displays Git branch and working-tree status](assets/git-status.png)
+
+### 历史命令自动建议
+
+![A suggested history command appears while typing](assets/autosuggestions.png)
+
+### 命令语法高亮与错误提示
+
+![Valid commands are green and unknown commands are red](assets/syntax-highlighting.png)
+
+## 常用参数
+
+```bash
+# 指定目标用户
+bash install.sh -y --user bell
+
+# 不修改默认登录 Shell
+bash install.sh -y --no-chsh
+
+# 仅删除 easy-command 管理的 .zshrc 配置区块
+bash install.sh --uninstall
+
+# 启用可选的目录跳转、模糊搜索和 Git 快捷操作
+bash install.sh -y --with-zoxide --with-fzf --with-git-aliases
+```
+
+`zoxide` 提供 `z <关键词>` 目录跳转；`fzf` 提供历史命令和文件的模糊搜索；Git 快捷操作使用 `ec-` 前缀，例如 `git ec-status`，不会覆盖已有别名。
+
+## 系统要求
+
+- macOS：需预先安装 Homebrew。
+- Ubuntu / Debian：脚本会使用 `apt-get` 安装依赖。
+
+脚本需要 `sudo` 权限安装软件包和切换默认 Shell。没有 sudo 权限时，请使用 `--no-chsh`，并由管理员预先安装 Zsh。
+
+## 配置与回退
+
+安装器只管理 `~/.zshrc` 中带有 `easy-command` 标记的配置区块。每次更新前会创建带时间戳的备份。执行 `--uninstall` 仅删除该托管区块，不会删除 Oh My Zsh、插件、命令历史或其他个人配置。
+
+安装内容：
+
+```text
+~/.easy-command/oh-my-zsh
+~/.zshrc
+~/.zsh_history
+```
+
+## 安全说明
+
+首次使用时，建议先下载并审阅脚本：
+
+```bash
+curl -fsSLO https://raw.githubusercontent.com/UnionSchool/easy-command/main/install.sh
+less install.sh
+bash install.sh -y
+```
+
+生产环境建议固定到发布标签，而不是直接使用 `main`：
+
+```bash
+npx easy-command@2.0.2 -y
+```
+
+或者不使用 npm：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/UnionSchool/easy-command/v2.0.2/install.sh | bash -s -- -y
+```
+
+## 许可
+
+[MIT](LICENSE)

package/install.sh

@@ -2,59 +2,68 @@
 
 set -Eeuo pipefail
 
-readonly VERSION='1.0.4'
+readonly VERSION='2.0.2'
 readonly BEGIN_MARKER='# >>> easy-command zsh >>>'
 readonly END_MARKER='# <<< easy-command zsh <<<'
+readonly BASE_DIR_NAME='.easy-command'
 
+ACTION='install'
 ASSUME_YES=false
 CHANGE_LOGIN_SHELL=true
-UNINSTALL=false
+DRY_RUN=false
+ENABLE_ZOXIDE='auto'
+ENABLE_FZF='auto'
+ENABLE_GIT_ALIASES='auto'
 TARGET_USER="${SUDO_USER:-${USER}}"
+TARGET_HOME=''
 
 info() { printf '\033[1;32m[easy-command]\033[0m %s\n' "$*"; }
 warn() { printf '\033[1;33m[easy-command]\033[0m %s\n' "$*" >&2; }
 fail() { printf '\033[1;31m[easy-command]\033[0m %s\n' "$*" >&2; exit 1; }
+ok() { printf '\033[1;32m[ok]\033[0m %s\n' "$*"; }
+check_warning() { printf '\033[1;33m[warn]\033[0m %s\n' "$*"; }
+check_error() { printf '\033[1;31m[error]\033[0m %s\n' "$*"; }
 
 usage() {
     cat <<'EOF'
-Usage: install.sh [options]
+Usage: easy-command [command] [options]
+
+Commands:
+  install             Install and configure easy-command (default).
+  doctor              Check the Shell, dependencies, repositories and .zshrc block.
+  repair              Restore missing dependencies, repositories and managed configuration.
+  update              Safely update managed repositories and refresh managed configuration.
 
 Options:
-  --yes, -y         Run without confirmation.
-  --user USER       Configure this user. Defaults to the invoking user.
-  --no-chsh         Do not change the user's default login shell to zsh.
-  --uninstall       Remove only the easy-command managed .zshrc block.
-  --help, -h        Show this help.
+  --yes, -y           Run without confirmation.
+  --user USER         Configure this user. Defaults to the invoking user.
+  --no-chsh           Do not change the user's default login shell to zsh.
+  --dry-run           Preview changes without installing, writing files, or using sudo.
+  --with-zoxide       Enable optional zoxide directory jumping.
+  --without-zoxide    Disable zoxide in the managed configuration.
+  --with-fzf          Enable optional fzf history and file searching.
+  --without-fzf       Disable fzf in the managed configuration.
+  --with-git-aliases  Add non-conflicting global Git aliases prefixed with ec-.
+  --without-git-aliases
+                    Remove global Git aliases managed by easy-command.
+  --uninstall         Remove only the easy-command managed .zshrc block.
+  --help, -h          Show this help.
 EOF
 }
 
-while (($#)); do
-    case "$1" in
-        --yes|-y) ASSUME_YES=true ;;
-        --user)
-            shift
-            (($#)) || fail '--user requires a value.'
-            TARGET_USER="$1"
-            ;;
-        --no-chsh) CHANGE_LOGIN_SHELL=false ;;
-        --uninstall) UNINSTALL=true ;;
-        --help|-h)
-            usage
-            exit 0
-            ;;
-        *) fail "Unknown option: $1" ;;
-    esac
-    shift
-done
-
-TARGET_HOME="$(getent passwd "$TARGET_USER" | cut -d: -f6 2>/dev/null || true)"
-if [[ -z "$TARGET_HOME" && "$(uname -s)" == 'Darwin' ]]; then
-    TARGET_HOME="$(dscl . -read "/Users/$TARGET_USER" NFSHomeDirectory | awk '{print $2}')"
-fi
-[[ -n "$TARGET_HOME" && -d "$TARGET_HOME" ]] || fail "Cannot determine home directory for $TARGET_USER."
+command_preview() {
+    local output=''
+    local part
+    for part in "$@"; do
+        output+="$(printf '%q' "$part") "
+    done
+    info "[dry-run] ${output% }"
+}
 
 run_as_root() {
-    if [[ "$EUID" -eq 0 ]]; then
+    if "$DRY_RUN"; then
+        command_preview sudo "$@"
+    elif [[ "$EUID" -eq 0 ]]; then
         "$@"
     elif command -v sudo >/dev/null 2>&1; then
         sudo "$@"
@@ -64,64 +73,197 @@ run_as_root() {
 }
 
 run_as_user() {
-    if [[ "$EUID" -eq 0 && "$TARGET_USER" != 'root' ]]; then
-        runuser -u "$TARGET_USER" -- "$@"
+    if "$DRY_RUN"; then
+        if [[ "$EUID" -eq 0 && "$TARGET_USER" != 'root' ]]; then
+            if command -v runuser >/dev/null 2>&1; then
+                command_preview runuser -u "$TARGET_USER" -- "$@"
+            else
+                command_preview sudo -u "$TARGET_USER" -- "$@"
+            fi
+        else
+            command_preview "$@"
+        fi
+    elif [[ "$EUID" -eq 0 && "$TARGET_USER" != 'root' ]]; then
+        if command -v runuser >/dev/null 2>&1; then
+            runuser -u "$TARGET_USER" -- "$@"
+        elif command -v sudo >/dev/null 2>&1; then
+            sudo -u "$TARGET_USER" -- "$@"
+        else
+            fail 'runuser or sudo is required to run commands as the target user.'
+        fi
     else
         "$@"
     fi
 }
 
+write_file() {
+    local source_file="$1"
+    local destination_file="$2"
+
+    if "$DRY_RUN"; then
+        command_preview cp "$source_file" "$destination_file"
+        return
+    fi
+
+    cp "$source_file" "$destination_file"
+    chown "$TARGET_USER" "$destination_file" 2>/dev/null || true
+}
+
+determine_target_home() {
+    if command -v getent >/dev/null 2>&1; then
+        TARGET_HOME="$(getent passwd "$TARGET_USER" | cut -d: -f6 2>/dev/null || true)"
+    fi
+    if [[ -z "$TARGET_HOME" && "$(uname -s)" == 'Darwin' ]]; then
+        TARGET_HOME="$(dscl . -read "/Users/$TARGET_USER" NFSHomeDirectory | awk '{print $2}')"
+    fi
+    [[ -n "$TARGET_HOME" && -d "$TARGET_HOME" ]] || fail "Cannot determine home directory for $TARGET_USER."
+}
+
 backup_file() {
     local file="$1"
     [[ -f "$file" ]] || return 0
 
     local backup="${file}.easy-command-backup-$(date +%Y%m%d%H%M%S)"
-    cp "$file" "$backup"
+    local sequence=1
+    while [[ -e "$backup" ]]; do
+        backup="${file}.easy-command-backup-$(date +%Y%m%d%H%M%S)-${sequence}"
+        sequence=$((sequence + 1))
+    done
+    if "$DRY_RUN"; then
+        command_preview cp "$file" "$backup"
+    else
+        cp "$file" "$backup"
+        chown "$TARGET_USER" "$backup" 2>/dev/null || true
+    fi
     info "Backed up $file to $backup"
 }
 
-remove_managed_block() {
+managed_block_is_valid() {
     local zshrc="$TARGET_HOME/.zshrc"
     [[ -f "$zshrc" ]] || return 0
 
-    local temp_file
-    temp_file="$(mktemp)"
-    awk -v begin="$BEGIN_MARKER" -v end="$END_MARKER" '
-        $0 == begin { skipping = 1; next }
-        $0 == end { skipping = 0; next }
-        !skipping { print }
-    ' "$zshrc" > "$temp_file"
-    cat "$temp_file" > "$zshrc"
-    rm -f "$temp_file"
-    chown "$TARGET_USER" "$zshrc" 2>/dev/null || true
+    local begin_count end_count
+    begin_count="$(grep -Fxc "$BEGIN_MARKER" "$zshrc" || true)"
+    end_count="$(grep -Fxc "$END_MARKER" "$zshrc" || true)"
+    [[ "$begin_count" == '0' && "$end_count" == '0' ]] || [[ "$begin_count" == '1' && "$end_count" == '1' ]]
+}
+
+managed_option_enabled() {
+    local option="$1"
+    local zshrc="$TARGET_HOME/.zshrc"
+
+    [[ -f "$zshrc" ]] && grep -Fqx "# easy-command: ${option}" "$zshrc"
+}
+
+resolve_option() {
+    local requested="$1"
+    local marker="$2"
+
+    if [[ "$requested" == 'auto' ]]; then
+        if managed_option_enabled "$marker"; then
+            printf 'true'
+        else
+            printf 'false'
+        fi
+    else
+        printf '%s' "$requested"
+    fi
 }
 
 install_packages() {
+    local packages=(zsh git)
+    [[ "$(resolve_option "$ENABLE_ZOXIDE" 'zoxide')" == 'true' ]] && packages+=(zoxide)
+    [[ "$(resolve_option "$ENABLE_FZF" 'fzf')" == 'true' ]] && packages+=(fzf)
+
     case "$(uname -s)" in
         Darwin)
             command -v brew >/dev/null 2>&1 || fail 'Homebrew is required on macOS: https://brew.sh'
-            brew install zsh git
+            run_as_user brew install "${packages[@]}"
             ;;
         Linux)
             command -v apt-get >/dev/null 2>&1 || fail 'Only Ubuntu/Debian (apt-get) is supported on Linux.'
             run_as_root apt-get update
-            run_as_root env DEBIAN_FRONTEND=noninteractive apt-get install -y zsh git
+            run_as_root env DEBIAN_FRONTEND=noninteractive apt-get install -y "${packages[@]}"
             ;;
         *) fail "Unsupported operating system: $(uname -s)" ;;
     esac
 }
 
-install_repository() {
+ensure_repository() {
     local repository="$1"
     local destination="$2"
-    [[ -d "$destination/.git" ]] && return 0
 
-    mkdir -p "$(dirname "$destination")"
+    if [[ -d "$destination/.git" ]]; then
+        return 0
+    fi
+    if [[ -e "$destination" ]]; then
+        fail "Expected Git repository at $destination, but the path is not a repository. Run repair after moving the path aside."
+    fi
+
+    if "$DRY_RUN"; then
+        command_preview mkdir -p "$(dirname "$destination")"
+    else
+        mkdir -p "$(dirname "$destination")"
+        chown "$TARGET_USER" "$(dirname "$destination")" 2>/dev/null || true
+    fi
     run_as_user git clone --depth 1 "$repository" "$destination"
 }
 
+update_repository() {
+    local destination="$1"
+    [[ -d "$destination/.git" ]] || return 0
+
+    if ! run_as_user git -C "$destination" diff --quiet --ignore-submodules --; then
+        warn "Skipped $destination because it has local changes."
+        return 0
+    fi
+    run_as_user git -C "$destination" pull --ff-only
+}
+
+ensure_repositories() {
+    local base_dir="$TARGET_HOME/$BASE_DIR_NAME"
+    ensure_repository 'https://github.com/ohmyzsh/ohmyzsh.git' "$base_dir/oh-my-zsh"
+    ensure_repository 'https://github.com/zsh-users/zsh-autosuggestions.git' "$base_dir/oh-my-zsh/custom/plugins/zsh-autosuggestions"
+    ensure_repository 'https://github.com/zsh-users/zsh-syntax-highlighting.git' "$base_dir/oh-my-zsh/custom/plugins/zsh-syntax-highlighting"
+}
+
+update_repositories() {
+    local base_dir="$TARGET_HOME/$BASE_DIR_NAME/oh-my-zsh"
+    update_repository "$base_dir"
+    update_repository "$base_dir/custom/plugins/zsh-autosuggestions"
+    update_repository "$base_dir/custom/plugins/zsh-syntax-highlighting"
+}
+
+remove_managed_block() {
+    local zshrc="$TARGET_HOME/.zshrc"
+    [[ -f "$zshrc" ]] || return 0
+    managed_block_is_valid || fail "Managed .zshrc block is incomplete or duplicated. Refusing to change $zshrc; restore a backup or repair the markers manually."
+
+    if "$DRY_RUN"; then
+        info "[dry-run] Would remove the managed block from $zshrc"
+        return 0
+    fi
+
+    local temp_file
+    temp_file="$(mktemp)"
+    awk -v begin="$BEGIN_MARKER" -v end="$END_MARKER" '
+        $0 == begin { skipping = 1; next }
+        $0 == end { skipping = 0; next }
+        !skipping { print }
+    ' "$zshrc" > "$temp_file"
+    write_file "$temp_file" "$zshrc"
+    rm -f "$temp_file"
+}
+
 write_zshrc_block() {
     local zshrc="$TARGET_HOME/.zshrc"
+    managed_block_is_valid || fail "Managed .zshrc block is incomplete or duplicated. Refusing to change $zshrc; restore a backup or repair the markers manually."
+
+    if "$DRY_RUN"; then
+        info "[dry-run] Would write the managed configuration block to $zshrc"
+        return 0
+    fi
+
     local temp_file
     temp_file="$(mktemp)"
 
@@ -131,35 +273,92 @@ write_zshrc_block() {
         !skipping { print }
     ' "$zshrc" > "$temp_file"
 
-    cat >> "$temp_file" <<'EOF'
+    cat >> "$temp_file" <<EOF
 
 # >>> easy-command zsh >>>
 # Managed by easy-command. Re-run the installer to update this block.
-export ZSH="$HOME/.easy-command/oh-my-zsh"
+export ZSH="\$HOME/.easy-command/oh-my-zsh"
 ZSH_THEME="agnoster"
 plugins=(git zsh-autosuggestions zsh-syntax-highlighting)
 
-HISTFILE="$HOME/.zsh_history"
+HISTFILE="\$HOME/.zsh_history"
 HISTSIZE=10000
 SAVEHIST=10000
 setopt append_history share_history hist_ignore_dups
 ZSH_AUTOSUGGEST_STRATEGY=(history completion)
 ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE='fg=8'
 
-source "$ZSH/oh-my-zsh.sh"
+source "\$ZSH/oh-my-zsh.sh"
 
 ZSH_HIGHLIGHT_STYLES[command]='fg=green'
 ZSH_HIGHLIGHT_STYLES[builtin]='fg=green'
 ZSH_HIGHLIGHT_STYLES[function]='fg=green'
 ZSH_HIGHLIGHT_STYLES[alias]='fg=green'
 ZSH_HIGHLIGHT_STYLES[unknown-token]='fg=red,bold'
+EOF
+
+    if [[ "$(resolve_option "$ENABLE_ZOXIDE" 'zoxide')" == 'true' ]]; then
+        cat >> "$temp_file" <<'EOF'
+
+# easy-command: zoxide
+if command -v zoxide >/dev/null 2>&1; then
+    eval "$(zoxide init zsh)"
+fi
+EOF
+    fi
+
+    if [[ "$(resolve_option "$ENABLE_FZF" 'fzf')" == 'true' ]]; then
+        cat >> "$temp_file" <<'EOF'
+
+# easy-command: fzf
+if [[ -r /usr/share/doc/fzf/examples/key-bindings.zsh ]]; then
+    source /usr/share/doc/fzf/examples/key-bindings.zsh
+elif command -v brew >/dev/null 2>&1 && [[ -r "$(brew --prefix)/opt/fzf/shell/key-bindings.zsh" ]]; then
+    source "$(brew --prefix)/opt/fzf/shell/key-bindings.zsh"
+fi
+EOF
+    fi
+
+    cat >> "$temp_file" <<'EOF'
 # <<< easy-command zsh <<<
 EOF
 
     backup_file "$zshrc"
-    cat "$temp_file" > "$zshrc"
+    write_file "$temp_file" "$zshrc"
     rm -f "$temp_file"
-    chown "$TARGET_USER" "$zshrc" 2>/dev/null || true
+}
+
+configure_git_aliases() {
+    local enabled
+    enabled="$(resolve_option "$ENABLE_GIT_ALIASES" 'git-aliases')"
+
+    local aliases=(
+        'ec-status=status --short --branch'
+        'ec-log=log --oneline --graph --decorate -12'
+        'ec-last=log -1 --stat'
+    )
+    local entry name value
+    for entry in "${aliases[@]}"; do
+        name="${entry%%=*}"
+        value="${entry#*=}"
+        if "$DRY_RUN"; then
+            if [[ "$enabled" == 'true' ]]; then
+                command_preview git config --global "alias.$name" "$value"
+            elif [[ "$ENABLE_GIT_ALIASES" == 'false' ]]; then
+                command_preview git config --global --unset "alias.$name"
+            fi
+            continue
+        fi
+        if [[ "$enabled" == 'true' ]]; then
+            if run_as_user git config --global --get "alias.$name" >/dev/null 2>&1; then
+                check_warning "Git alias $name already exists; leaving it unchanged."
+            else
+                run_as_user git config --global "alias.$name" "$value"
+            fi
+        elif [[ "$ENABLE_GIT_ALIASES" == 'false' ]]; then
+            run_as_user git config --global --unset "alias.$name" 2>/dev/null || true
+        fi
+    done
 }
 
 change_login_shell() {
@@ -167,34 +366,164 @@ change_login_shell() {
 
     local zsh_path
     zsh_path="$(command -v zsh)"
-    grep -qx "$zsh_path" /etc/shells || fail "$zsh_path is not listed in /etc/shells."
+    if ! grep -qx "$zsh_path" /etc/shells; then
+        if [[ -x /bin/zsh ]] && grep -qx '/bin/zsh' /etc/shells; then
+            warn "$zsh_path is not listed in /etc/shells; using /bin/zsh as the login shell."
+            zsh_path='/bin/zsh'
+        else
+            fail "$zsh_path is not listed in /etc/shells. Use --no-chsh or add the path to /etc/shells first."
+        fi
+    fi
     run_as_root chsh -s "$zsh_path" "$TARGET_USER"
 }
 
-main() {
-    if "$UNINSTALL"; then
-        backup_file "$TARGET_HOME/.zshrc"
-        remove_managed_block
-        info 'Removed the easy-command managed .zshrc block.'
-        exit 0
+confirm() {
+    "$DRY_RUN" && return 0
+    "$ASSUME_YES" && return 0
+
+    local answer
+    read -r -p "$1 [y/N] " answer
+    [[ "$answer" =~ ^[Yy]$ ]] || exit 0
+}
+
+doctor() {
+    local errors=0
+    local zshrc="$TARGET_HOME/.zshrc"
+    local base_dir="$TARGET_HOME/$BASE_DIR_NAME/oh-my-zsh"
+    local configured_shell=''
+
+    info "Checking easy-command for $TARGET_USER"
+    if command -v getent >/dev/null 2>&1; then
+        configured_shell="$(getent passwd "$TARGET_USER" | cut -d: -f7 2>/dev/null || true)"
+    fi
+    if [[ -z "$configured_shell" && "$(uname -s)" == 'Darwin' ]]; then
+        configured_shell="$(dscl . -read "/Users/$TARGET_USER" UserShell | awk '{print $2}')"
+    fi
+    if [[ "$configured_shell" == *zsh ]]; then
+        ok "Login shell: $configured_shell"
+    else
+        check_warning "Login shell is ${configured_shell:-unknown}; run install without --no-chsh to switch to zsh."
     fi
 
-    if ! "$ASSUME_YES"; then
-        read -r -p "Install easy-command for $TARGET_USER? [y/N] " answer
-        [[ "$answer" =~ ^[Yy]$ ]] || exit 0
+    local command_name
+    for command_name in zsh git; do
+        if command -v "$command_name" >/dev/null 2>&1; then
+            ok "Command available: $command_name"
+        else
+            check_error "Missing command: $command_name"
+            errors=$((errors + 1))
+        fi
+    done
+
+    local repository
+    for repository in "$base_dir" "$base_dir/custom/plugins/zsh-autosuggestions" "$base_dir/custom/plugins/zsh-syntax-highlighting"; do
+        if [[ -d "$repository/.git" ]]; then
+            ok "Repository available: $repository"
+        else
+            check_error "Missing repository: $repository"
+            errors=$((errors + 1))
+        fi
+    done
+
+    local begin_count=0 end_count=0
+    if [[ -f "$zshrc" ]]; then
+        begin_count="$(grep -Fxc "$BEGIN_MARKER" "$zshrc" || true)"
+        end_count="$(grep -Fxc "$END_MARKER" "$zshrc" || true)"
+    fi
+    if [[ "$begin_count" == '1' && "$end_count" == '1' ]]; then
+        ok 'Managed .zshrc block is complete.'
+    else
+        check_error "Managed .zshrc block is invalid (begin: $begin_count, end: $end_count). Restore a backup or repair the markers manually."
+        errors=$((errors + 1))
     fi
 
-    install_packages
+    if command -v zsh >/dev/null 2>&1 && [[ -f "$zshrc" ]]; then
+        if zsh -n "$zshrc"; then
+            ok '.zshrc syntax check passed.'
+        else
+            check_error '.zshrc syntax check failed.'
+            errors=$((errors + 1))
+        fi
+    fi
 
-    local base_dir="$TARGET_HOME/.easy-command"
-    install_repository 'https://github.com/ohmyzsh/ohmyzsh.git' "$base_dir/oh-my-zsh"
-    install_repository 'https://github.com/zsh-users/zsh-autosuggestions.git' "$base_dir/oh-my-zsh/custom/plugins/zsh-autosuggestions"
-    install_repository 'https://github.com/zsh-users/zsh-syntax-highlighting.git' "$base_dir/oh-my-zsh/custom/plugins/zsh-syntax-highlighting"
+    if ((errors > 0)); then
+        return 1
+    fi
+}
 
-    write_zshrc_block
-    change_login_shell
+parse_args() {
+    while (($#)); do
+        case "$1" in
+            install|doctor|repair|update)
+                ACTION="$1"
+                ;;
+            --yes|-y) ASSUME_YES=true ;;
+            --user)
+                shift
+                (($#)) || fail '--user requires a value.'
+                TARGET_USER="$1"
+                ;;
+            --no-chsh) CHANGE_LOGIN_SHELL=false ;;
+            --dry-run) DRY_RUN=true ;;
+            --with-zoxide) ENABLE_ZOXIDE=true ;;
+            --without-zoxide) ENABLE_ZOXIDE=false ;;
+            --with-fzf) ENABLE_FZF=true ;;
+            --without-fzf) ENABLE_FZF=false ;;
+            --with-git-aliases) ENABLE_GIT_ALIASES=true ;;
+            --without-git-aliases) ENABLE_GIT_ALIASES=false ;;
+            --uninstall) ACTION='uninstall' ;;
+            --help|-h)
+                usage
+                exit 0
+                ;;
+            *) fail "Unknown option or command: $1" ;;
+        esac
+        shift
+    done
+}
+
+main() {
+    parse_args "$@"
+    determine_target_home
 
-    info "Installed easy-command $VERSION for $TARGET_USER. Reconnect or run: exec zsh -l"
+    case "$ACTION" in
+        doctor)
+            doctor
+            ;;
+        uninstall)
+            confirm "Remove the easy-command managed configuration for $TARGET_USER?"
+            backup_file "$TARGET_HOME/.zshrc"
+            remove_managed_block
+            info 'Removed the easy-command managed .zshrc block.'
+            ;;
+        install)
+            confirm "Install easy-command $VERSION for $TARGET_USER?"
+            install_packages
+            ensure_repositories
+            change_login_shell
+            write_zshrc_block
+            configure_git_aliases
+            info "Installed easy-command $VERSION for $TARGET_USER. Reconnect or run: exec zsh -l"
+            ;;
+        repair)
+            CHANGE_LOGIN_SHELL=false
+            confirm "Repair easy-command for $TARGET_USER?"
+            install_packages
+            ensure_repositories
+            write_zshrc_block
+            configure_git_aliases
+            info "Repaired easy-command for $TARGET_USER. Reconnect or run: exec zsh -l"
+            ;;
+        update)
+            CHANGE_LOGIN_SHELL=false
+            confirm "Update easy-command repositories for $TARGET_USER?"
+            ensure_repositories
+            update_repositories
+            write_zshrc_block
+            configure_git_aliases
+            info "Updated easy-command for $TARGET_USER. Reconnect or run: exec zsh -l"
+            ;;
+    esac
 }
 
-main
+main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easy-command",
-  "version": "1.0.4",
+  "version": "2.0.2",
   "description": "Configure a polished Zsh terminal with one command.",
   "license": "MIT",
   "bin": {
@@ -8,8 +8,10 @@
   },
   "files": [
     "bin",
+    "assets",
     "install.sh",
     "README.md",
+    "README_CN.md",
     "LICENSE"
   ],
   "repository": {