feat: add script catalog and -h help for all dotfile scripts

Introduce ff script -h with auto descriptions, shared help.sh, and usage flags across script/*.sh.

Co-authored-by: Cursor <cursoragent@cursor.com>

script/scan-port.sh

@@ -1,25 +1,42 @@
 #!/bin/bash
+# 对指定 IP 进行 TCP 端口扫描
 
-# 端口扫描脚本
-# 用法: ./scan-port.sh <IP地址> [端口范围]
-# 示例: ./scan-port.sh 192.168.1.1
-# 示例: ./scan-port.sh 192.168.1.1 80,443,8080
-# 示例: ./scan-port.sh 192.168.1.1 1-1000
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/common/help.sh"
+
+usage() {
+    cat <<'EOF'
+用法: scan-port <IP> [端口范围]
+
+扫描目标 IP 的 TCP 端口（使用 nc）。
+
+参数:
+  IP            目标 IPv4 地址（必填）
+  端口范围      可选。默认扫描常用端口列表。
+                支持: 80,443,8080  或  1-1000
+
+选项:
+  -h, --help  显示此帮助
+
+示例:
+  scan-port 192.168.1.1
+  scan-port 192.168.1.1 22,80,443
+  scan-port 192.168.1.1 1-1000
+EOF
+}
+
+dotfile_help_requested "${1:-}" && dotfile_show_help
 
-# 检查是否提供了 IP 地址参数
 if [ -z "$1" ]; then
-    echo "错误: 请提供要扫描的 IP 地址"
-    echo "用法: $0 <IP地址> [端口范围]"
-    echo "示例: $0 192.168.1.1"
-    echo "示例: $0 192.168.1.1 80,443,8080"
-    echo "示例: $0 192.168.1.1 1-1000"
+    echo "错误: 请提供要扫描的 IP 地址" >&2
+    usage
     exit 1
 fi
 
 TARGET_IP="$1"
-TIMEOUT=1  # 连接超时时间（秒）
+TIMEOUT=1
 
-# 验证 IP 地址格式（简单验证）
 if ! [[ "$TARGET_IP" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
     echo "错误: 无效的 IP 地址格式: $TARGET_IP"
     exit 1
@@ -29,45 +46,33 @@ echo "=========================================="
 echo "正在扫描 IP: $TARGET_IP"
 echo "=========================================="
 
-# 检查是否有 nc (netcat) 命令
 if ! command -v nc &>/dev/null; then
     echo "错误: 找不到 nc (netcat) 命令。"
-    echo "请安装 netcat:"
-    echo "  macOS: brew install netcat"
-    echo "  Linux: sudo apt-get install netcat 或 sudo yum install nc"
     exit 1
 fi
 
-# 确定要扫描的端口
 if [ -z "$2" ]; then
-    # 如果没有指定端口，扫描常用端口
     PORTS=(21 22 23 25 53 80 110 111 135 139 143 443 445 993 995 1723 3306 3389 5432 5900 8080 8443)
     echo "使用默认常用端口列表"
 else
-    # 解析端口参数
     PORT_SPEC="$2"
-    
-    # 检查是否是范围格式 (例如: 1-1000)
+
     if [[ "$PORT_SPEC" =~ ^[0-9]+-[0-9]+$ ]]; then
         START_PORT=$(echo "$PORT_SPEC" | cut -d'-' -f1)
         END_PORT=$(echo "$PORT_SPEC" | cut -d'-' -f2)
-        
+
         if [ "$START_PORT" -gt "$END_PORT" ]; then
             echo "错误: 起始端口 ($START_PORT) 不能大于结束端口 ($END_PORT)"
             exit 1
         fi
-        
+
         PORTS=($(seq "$START_PORT" "$END_PORT"))
-        echo "扫描端口范围: $START_PORT-$END_PORT (共 $((END_PORT - START_PORT + 1)) 个端口)"
-    # 检查是否是逗号分隔的端口列表 (例如: 80,443,8080)
+        echo "扫描端口范围: $START_PORT-$END_PORT"
     elif [[ "$PORT_SPEC" =~ ^[0-9,]+$ ]]; then
-        IFS=',' read -ra PORTS <<< "$PORT_SPEC"
+        IFS=',' read -ra PORTS <<<"$PORT_SPEC"
         echo "扫描指定端口: $PORT_SPEC"
     else
         echo "错误: 无效的端口格式: $PORT_SPEC"
-        echo "支持的格式:"
-        echo "  - 逗号分隔: 80,443,8080"
-        echo "  - 范围: 1-1000"
         exit 1
     fi
 fi
@@ -75,20 +80,14 @@ fi
 echo "超时设置: ${TIMEOUT}秒"
 echo "------------------------------------------------------"
 
-# 统计变量
 OPEN_PORTS=()
 CLOSED_COUNT=0
 TOTAL_PORTS=${#PORTS[@]}
 
-# 扫描端口函数
 scan_port() {
     local port=$1
     local ip=$2
-    
-    # 使用 nc 扫描端口
-    # -z: 只扫描，不发送数据
-    # -v: 详细输出
-    # -w: 超时时间
+
     if nc -z -v -w "$TIMEOUT" "$ip" "$port" 2>&1 | grep -q "succeeded\|open"; then
         echo "✅ 端口 $port: 开放"
         return 0
@@ -97,7 +96,6 @@ scan_port() {
     fi
 }
 
-# 并行扫描端口（使用后台任务）
 for port in "${PORTS[@]}"; do
     if scan_port "$port" "$TARGET_IP"; then
         OPEN_PORTS+=("$port")
@@ -106,7 +104,6 @@ for port in "${PORTS[@]}"; do
     fi
 done
 
-# 等待所有后台任务完成
 wait
 
 echo "------------------------------------------------------"
@@ -128,4 +125,3 @@ else
 fi
 
 echo "=========================================="
-