@wxuns/zp-cli 0.0.1

package/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to npm
+
+on:
+  # 推送版本标签时触发 (例如 v1.0.0, v1.1.0)
+  push:
+    tags:
+      - 'v*'
+
+  # 也可以手动触发
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    
+    steps:
+      # 1. 检出代码
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      # 2. 设置 Node.js 环境
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+
+      # 3. 安装依赖
+      - name: Install dependencies
+        run: npm install
+
+      # 4. 运行测试 (如果有)
+      # - name: Run tests
+      #   run: npm test
+
+      # 5. 发布到 npm
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # 6. 创建 GitHub Release (可选)
+      - name: Create GitHub Release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+          draft: false
+          prerelease: false

package/DEBUG.md

@@ -0,0 +1,129 @@
+# zp-cli 本地调试指南
+
+## npm link 全局链接
+
+将本地项目链接到全局，使 `zp-cli` 命令直接指向本地代码，修改代码后立即生效。
+
+### 链接
+
+```bash
+cd D:/epg/codes/zp-cli
+npm link
+```
+
+执行后 `zp-cli` 命令将指向当前目录，可以直接使用：
+
+```bash
+zp-cli --help
+zp-cli init
+zp-cli upload ./some-file --server <服务器别名> --remote-path /tmp/test
+```
+
+### 取消链接
+
+```bash
+cd D:/epg/codes/zp-cli
+npm unlink -g zp-cli
+```
+
+或直接全局卸载：
+
+```bash
+npm uninstall -g zp-cli
+```
+
+### 验证链接状态
+
+```bash
+# 查看 zp-cli 命令指向的路径
+which zp-cli
+
+# 应输出类似：
+# /c/Users/<用户名>/AppData/Roaming/npm/zp-cli -> /d/epg/codes/zp-cli/bin/zp-cli.js
+```
+
+---
+
+## 调试流程
+
+### 1. 基础命令测试
+
+```bash
+# 帮助信息
+zp-cli --help
+zp-cli upload --help
+zp-cli init --help
+
+# 版本
+zp-cli -v
+
+# 配置路径
+zp-cli config path
+
+# 查看配置
+zp-cli config show
+```
+
+### 2. 初始化配置
+
+```bash
+# 生成 demo 配置
+zp-cli init
+
+# 编辑配置文件，填入真实的服务器信息
+notepad %USERPROFILE%\.zp-cli.json
+```
+
+### 3. 上传测试
+
+```bash
+# 指定服务器和远程路径（跳过 Git 匹配）
+zp-cli upload ./test.txt --server <服务器别名> --remote-path /tmp/test.txt
+
+# 上传目录
+zp-cli upload ./dist --server <服务器别名> --remote-path /tmp/dist
+
+# 在 Git 仓库内，自动匹配（需要先配好 mappings）
+zp-cli upload ./vue_zte3.0/dist
+```
+
+### 4. 查看部署结果
+
+```bash
+# 登录服务器验证（根据实际配置替换信息）
+ssh <用户名>@<服务器地址> "ls -la /tmp/"
+```
+
+---
+
+## 常见问题
+
+### 命令找不到
+
+```bash
+# 检查 npm 全局 bin 目录是否在 PATH 中
+npm config get prefix
+
+# Windows 下通常在：
+# C:\Users\<用户名>\AppData\Roaming\npm
+```
+
+### 修改代码后不生效
+
+npm link 后修改代码会立即生效，无需重新 link。如果出现缓存问题：
+
+```bash
+# 重新 link
+npm unlink -g zp-cli
+npm link
+```
+
+### 权限问题（Linux/Mac）
+
+```bash
+sudo npm link
+```
+
+### Windows 上 tar 命令报错
+
+确保使用 Git Bash 终端运行，Git Bash 自带 tar 命令。或安装 WSL。

package/README.md

@@ -0,0 +1,289 @@
+# zp-cli
+
+将本地代码通过 SSH 部署到远程服务器的命令行工具。支持单文件/目录上传，支持同一仓库不同子目录部署到不同服务器。
+
+## 安装
+
+```bash
+npm install -g @wxuns/zp-cli
+```
+
+## 快速开始
+
+```bash
+# 1. 生成配置文件模板
+zp-cli init
+
+# 2. 编辑配置文件，填入你的服务器信息
+#    Windows: notepad %USERPROFILE%\.zp-cli.json
+#    Linux/Mac: vim ~/.zp-cli.json
+
+# 3. 上传文件
+zp-cli upload ./dist/index.html
+zp-cli upload ./dist
+```
+
+---
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `zp-cli init` | 生成 demo 配置文件 `~/.zp-cli.json` |
+| `zp-cli upload <路径>` | 上传文件或目录到远程服务器 |
+| `zp-cli config show` | 查看当前配置内容 |
+| `zp-cli config path` | 显示配置文件路径 |
+| `zp-cli --help` | 查看帮助 |
+| `zp-cli -v` | 查看版本 |
+
+### upload 命令选项
+
+```bash
+zp-cli upload <路径> [选项]
+
+选项:
+  -s, --server <别名>       指定目标服务器（覆盖自动匹配）
+  -r, --remote-path <路径>  指定远程目标路径（覆盖配置中的默认值）
+```
+
+---
+
+## 配置文件说明
+
+配置文件路径：`~/.zp-cli.json`（Windows 下为 `%USERPROFILE%\.zp-cli.json`）
+
+执行 `zp-cli init` 会生成如下 demo 配置：
+
+```jsonc
+{
+  "servers": [
+    {
+      "alias": "test-server",          // 服务器别名，命令行中用于指定目标
+      "host": "192.168.1.100",          // 服务器 IP 或域名
+      "port": 22,                       // SSH 端口，默认 22
+      "username": "root",               // SSH 登录用户名
+      "password": "your-password",      // 密码认证（与 privateKeyPath 二选一）
+      "privateKeyPath": "~/.ssh/id_rsa",// 私钥认证（与 password 二选一）
+      "defaultRemotePath": "/home/www", // 默认远程目录（可被 --remote-path 覆盖）
+      "rootPassword": ""                // root 密码，需要 su root 时填写
+    }
+  ],
+
+  "mappings": [
+    {
+      "gitRemoteUrl": "git@github.com:yourorg/project.git",
+      "serverAlias": "test-server",
+      "remotePath": "/var/www/project",
+      "subdirectoryMappings": {}
+    }
+  ]
+}
+```
+
+### servers 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `alias` | string | **必填** | 服务器别名，用于 `--server` 参数和 `mappings` 中引用 |
+| `host` | string | **必填** | 服务器 IP 或域名 |
+| `port` | number | 选填 | SSH 端口，默认 `22` |
+| `username` | string | **必填** | 登录用户名 |
+| `password` | string | **条件必填** | 登录密码，与 `privateKeyPath` 至少填一个 |
+| `privateKeyPath` | string | **条件必填** | SSH 私钥路径，与 `password` 至少填一个。支持 `~` |
+| `defaultRemotePath` | string | 选填 | 默认远程部署目录，可被 `--remote-path` 覆盖 |
+| `rootPassword` | string | 选填 | root 密码，需要提权操作时填写 |
+
+> **条件必填**：`password` 和 `privateKeyPath` 至少填一个。同时存在时优先使用 `privateKeyPath`。
+
+### mappings 字段
+
+每条映射将一个 Git 仓库关联到服务器部署路径。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `gitRemoteUrl` | string | **必填** | Git 远程仓库地址，支持 SSH 和 HTTPS 两种格式（自动归一化匹配） |
+| `serverAlias` | string | **条件必填** | 目标服务器别名，有子映射时可省略 |
+| `remotePath` | string | **条件必填** | 远程部署根路径，有子映射时可省略 |
+| `subdirectoryMappings` | object | 选填 | 子目录映射，可将仓库不同子目录部署到不同路径/服务器 |
+
+> **条件必填**：如果所有文件都通过 `subdirectoryMappings` 映射到具体服务器和路径，则顶层 `serverAlias` 和 `remotePath` 可省略。否则必须填写。
+>
+> **优先级**：子目录映射 > 映射顶层 `serverAlias` / `remotePath`
+
+### 子目录映射（subdirectoryMappings）
+
+支持两种格式：
+
+**格式一：字符串 — 同服务器不同路径**
+
+```json
+"subdirectoryMappings": {
+  "web": "/var/www/project/frontend"
+}
+```
+
+上传 `./web/index.js` → 部署到 `/var/www/project/frontend/index.js`
+
+**格式二：对象 — 部署到不同服务器**
+
+```json
+"subdirectoryMappings": {
+  "api": {
+    "serverAlias": "backend-server",
+    "remotePath": "/opt/services/api"
+  }
+}
+```
+
+上传 `./api/main.py` → 部署到 `backend-server` 的 `/opt/services/api/main.py`
+
+**对象格式字段说明：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `serverAlias` | string | **必填** | 目标服务器别名 |
+| `remotePath` | string | **必填** | 该子目录在目标服务器上的部署路径 |
+
+**完整示例：**
+
+```json
+{
+  "servers": [
+    { "alias": "web-server",     "host": "10.0.0.1", "username": "root", "password": "xxx" },
+    { "alias": "backend-server", "host": "10.0.0.2", "username": "root", "password": "xxx" }
+  ],
+  "mappings": [
+    {
+      "gitRemoteUrl": "git@github.com:yourorg/mono-repo.git",
+      "serverAlias": "web-server",
+      "remotePath": "/var/www/mono",
+      "subdirectoryMappings": {
+        "web": "/var/www/mono/frontend",
+        "api": {
+          "serverAlias": "backend-server",
+          "remotePath": "/opt/services/api"
+        },
+        "config": "/etc/mono-repo"
+      }
+    }
+  ]
+}
+```
+
+对应部署结果：
+
+| 上传路径 | 目标服务器 | 远程路径 |
+|---------|-----------|---------|
+| `./web/index.js` | web-server | `/var/www/mono/frontend/index.js` |
+| `./api/main.py` | **backend-server** | `/opt/services/api/main.py` |
+| `./config/app.conf` | web-server | `/etc/mono-repo/app.conf` |
+| `./README.md` | web-server | `/var/www/mono/README.md` |
+
+**纯子目录映射示例**（顶层不设 serverAlias/remotePath，全部由子映射决定）：
+
+```json
+{
+  "servers": [
+    { "alias": "web-server",     "host": "10.0.0.1", "username": "root", "password": "xxx" },
+    { "alias": "backend-server", "host": "10.0.0.2", "username": "root", "password": "xxx" }
+  ],
+  "mappings": [
+    {
+      "gitRemoteUrl": "git@github.com:yourorg/full-stack.git",
+      "subdirectoryMappings": {
+        "frontend": {
+          "serverAlias": "web-server",
+          "remotePath": "/var/www/frontend"
+        },
+        "backend": {
+          "serverAlias": "backend-server",
+          "remotePath": "/opt/services/backend"
+        }
+      }
+    }
+  ]
+}
+```
+
+| 上传路径 | 目标服务器 | 远程路径 |
+|---------|-----------|---------|
+| `./frontend/index.html` | web-server | `/var/www/frontend/index.html` |
+| `./backend/app.py` | **backend-server** | `/opt/services/backend/app.py` |
+| `./README.md` | ❌ 报错 | 未匹配到子映射，且无顶层回退路径 |
+
+---
+
+## Git URL 匹配规则
+
+配置中的 `gitRemoteUrl` 和实际仓库的 `origin` 地址会自动归一化后匹配，以下写法等价：
+
+```
+git@github.com:org/repo.git          ←→  https://github.com/org/repo.git
+ssh://git@github.com:22/org/repo.git ←→  git@github.com:org/repo.git
+git@gitlab.com:group/sub/repo.git    ←→  https://gitlab.com/group/sub/repo.git
+```
+
+---
+
+## 部署流程
+
+执行 `zp-cli upload` 时的完整流程：
+
+```
+1. 检查本地路径是否存在
+2. 读取 ~/.zp-cli.json 配置
+3. 确定目标服务器和远程路径
+   ├─ 命令行指定了 --server / --remote-path → 直接使用
+   └─ 未指定 → 读取 .git/config 获取 origin 地址 → 匹配 mappings
+4. 建立 SSH 连接
+5. 如果是目录 → 本地 tar -czf 打包
+6. 上传文件到服务器 /tmp 临时目录
+7. 在服务器上解压/复制到目标路径
+8. 清理远程临时文件
+9. 关闭连接
+```
+
+---
+
+## 常见问题
+
+**Q: 报错"配置文件不存在"**
+A: 先执行 `zp-cli init` 生成配置文件。
+
+**Q: 报错"无法自动确定部署目标"**
+A: 当前目录不在 Git 仓库内，或配置文件中没有匹配的映射。可以用 `--server` 和 `--remote-path` 手动指定。
+
+**Q: 如何部署到同一台服务器的不同目录？**
+A: 在 `subdirectoryMappings` 中用字符串格式配置即可。
+
+**Q: 如何将仓库的不同子目录部署到不同服务器？**
+A: 在 `subdirectoryMappings` 中用对象格式，指定 `serverAlias` 和 `remotePath`。
+
+**Q: Windows 上打包报错？**
+A: 确保系统中有 `tar` 命令（Git Bash 自带）。或使用 WSL。
+
+---
+
+## 项目结构
+
+```
+zp-cli/
+├── package.json
+├── bin/
+│   └── zp-cli.js              # 主入口
+├── lib/
+│   ├── commands/
+│   │   ├── init.js             # 生成 demo 配置
+│   │   └── upload.js           # 上传部署逻辑
+│   ├── core/
+│   │   ├── configManager.js    # 配置读写
+│   │   ├── gitHelper.js        # Git 仓库感知、URL 归一化、路径映射
+│   │   └── sshDeployer.js      # SSH 连接、打包、上传、解压
+│   └── utils/
+│       └── logger.js           # 终端彩色输出
+└── README.md
+```
+
+## License
+
+MIT

package/bin/zp-cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+/**
+ * zp-cli - 命令行部署工具主入口
+ * 使用 commander 解析命令行参数，提供 init / upload / config 子命令
+ */
+const { Command } = require('commander');
+const chalk = require('chalk');
+const configManager = require('../lib/core/configManager');
+const logger = require('../lib/utils/logger');
+const pkg = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('zp-cli')
+  .description('zp-cli - 高效的命令行部署工具，将本地代码通过 SSH 部署到远程服务器')
+  .version(pkg.version, '-v, --version', '显示版本号');
+
+// ========== init 命令 ==========
+program
+  .command('init')
+  .alias('i')
+  .description('生成 demo 配置文件 ~/.zp-cli.json')
+  .action(async () => {
+    const initCmd = require('../lib/commands/init');
+    await initCmd.run();
+  });
+
+// ========== upload 命令 ==========
+program
+  .command('upload <路径>')
+  .alias('up')
+  .description('上传文件或目录到远程服务器')
+  .option('-s, --server <别名>', '指定目标服务器别名')
+  .option('-r, --remote-path <路径>', '指定远程目标路径（覆盖配置中的默认值）')
+  .action(async (localPath, options) => {
+    const uploadCmd = require('../lib/commands/upload');
+    await uploadCmd.run(localPath, options);
+  });
+
+// ========== config 命令（查看/管理配置） ==========
+const configCmd = program
+  .command('config')
+  .alias('c')
+  .description('查看和管理配置信息');
+
+configCmd
+  .command('show')
+  .alias('ls')
+  .description('显示当前配置文件内容')
+  .action(() => {
+    const config = configManager.loadConfig();
+    if (!config) {
+      logger.error('配置文件不存在，请先执行 ' + chalk.cyan('zp-cli init'));
+      process.exit(1);
+    }
+    logger.log(chalk.bold('\n📋 当前配置:\n'));
+    logger.log(JSON.stringify(config, null, 2));
+    logger.newline();
+    logger.log(chalk.gray(`配置文件路径: ${configManager.getConfigPath()}`));
+  });
+
+configCmd
+  .command('path')
+  .alias('p')
+  .description('显示配置文件路径')
+  .action(() => {
+    logger.log(configManager.getConfigPath());
+  });
+
+// ========== 未提供子命令时显示帮助 ==========
+program.on('command:*', () => {
+  logger.error(`未知命令: ${program.args.join(' ')}`);
+  logger.log('');
+  program.help();
+});
+
+// 如果没有输入任何命令，显示帮助
+if (process.argv.length <= 2) {
+  program.help();
+}
+
+program.parse(process.argv);

package/lib/commands/init.js

@@ -0,0 +1,93 @@
+/**
+ * init.js - 配置初始化命令
+ * 直接生成一个 demo 配置文件，用户自行修改
+ */
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const configManager = require('../core/configManager');
+
+/** demo 配置模板 */
+const DEMO_CONFIG = {
+  servers: [
+    {
+      alias: "test-server",
+      host: "192.168.1.100",
+      port: 22,
+      username: "root",
+      password: "your-password",
+      // privateKeyPath: "~/.ssh/id_rsa",  // 私钥认证，与 password 二选一
+      defaultRemotePath: "/home/www",
+      rootPassword: ""                       // 需要 su root 时填写
+    },
+    {
+      alias: "prod-server",
+      host: "10.0.0.1",
+      port: 22,
+      username: "deploy",
+      password: "",
+      privateKeyPath: "~/.ssh/id_rsa",
+      defaultRemotePath: "/home/www",
+      rootPassword: ""
+    }
+  ],
+
+  mappings: [
+    // ── 示例1：整个仓库部署到同一台服务器 ──
+    {
+      "gitRemoteUrl": "git@github.com:yourorg/simple-project.git",
+      "serverAlias": "test-server",
+      "remotePath": "/var/www/simple-project"
+    },
+
+    // ── 示例2：同一仓库，不同子目录部署到不同服务器（顶层 + 子映射混合） ──
+    {
+      "gitRemoteUrl": "git@github.com:yourorg/mono-repo.git",
+      "serverAlias": "test-server",
+      "remotePath": "/var/www/mono",
+      "subdirectoryMappings": {
+        "web": "/var/www/mono/frontend",
+        "api": {
+          "serverAlias": "prod-server",
+          "remotePath": "/opt/services/api"
+        }
+      }
+    },
+
+    // ── 示例3：纯子目录映射，serverAlias/remotePath 全在子映射里 ──
+    {
+      "gitRemoteUrl": "git@github.com:yourorg/full-stack.git",
+      "subdirectoryMappings": {
+        "frontend": {
+          "serverAlias": "test-server",
+          "remotePath": "/var/www/frontend"
+        },
+        "backend": {
+          "serverAlias": "prod-server",
+          "remotePath": "/opt/services/backend"
+        }
+      }
+    }
+  ]
+};
+
+/**
+ * 执行 init 命令
+ */
+async function run() {
+  const configPath = configManager.getConfigPath();
+
+  // 已存在则提示
+  if (configManager.configExists()) {
+    logger.warn(`配置文件已存在: ${configPath}`);
+    logger.log(chalk.gray('如需重新生成，请先手动删除该文件'));
+    return;
+  }
+
+  configManager.saveConfig(DEMO_CONFIG);
+  logger.success(`配置文件已生成: ${configPath}`);
+  logger.newline();
+  logger.log(chalk.bold('请编辑配置文件，填入你的服务器信息和仓库映射。'));
+  logger.log(chalk.gray('详细说明请参考 README.md 或执行 zp-cli init --help'));
+}
+
+module.exports = { run };