ssh-release 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.2.0 - 2026-06-26
+
+### Added
+
+- 增加首次发布指南，覆盖初始化、配置、预检、发布、列表和回滚流程。
+- 增加平台依赖说明，补充 macOS、Ubuntu/Debian、Windows 和 CI 中的 `sshpass`、OpenSSH、`tar`、远端 hash 命令要求。
+- `ssh-release init` 成功后输出下一步操作提示。
+- 配置文件缺失和 `sshpass` 缺失时输出更具体的下一步提示。
+- `ssh-release doctor` 增加本地 `tar`、`ssh`、`scp`、`sshpass` 和远端 hash 命令检查。
+
 ## 1.1.0 - 2026-06-26
 
 ### Added

package/README.md

@@ -11,7 +11,7 @@
 已实现：
 
 - `ssh-release init`：生成 `ssh-release.config.ts` 配置模板。
-- `ssh-release doctor`：检查配置、本地源路径、SSH 连接、远程目录、远端锁和远端 `tar`。
+- `ssh-release doctor`：检查配置、本地源路径、本地命令、SSH 连接、远程目录、远端 hash、远端锁和远端 `tar`。
 - `ssh-release deploy`：发布本地文件或目录。
 - `ssh-release list`：查看远程版本和当前版本。
 - `ssh-release rollback [version]`：回滚到上一个版本或指定版本。
@@ -55,6 +55,9 @@ ssh-release --help
 ssh-release --version
 ```
 
+首次接入步骤见 [docs/quick-start.md](https://github.com/JackEngineer/ssh-release/blob/main/docs/quick-start.md)。
+本机和 CI 依赖见 [docs/platform-requirements.md](https://github.com/JackEngineer/ssh-release/blob/main/docs/platform-requirements.md)。
+
 ## 本地开发
 
 ```bash
@@ -177,7 +180,9 @@ source files -> package -> upload -> release -> activate -> rollback
 ssh-release doctor
 ```
 
-`doctor` 会检查 `.ssh-release.lock`。没有锁时正常通过；如果发现锁，会以 `warn` 显示锁路径、pid、创建时间和安全清理提示。
+`doctor` 会先检查本地 `tar`、`ssh`、`scp`，使用密码登录时还会检查 `sshpass`。本地检查失败时不会继续连接远端。
+
+`doctor` 也会检查 `.ssh-release.lock`。没有锁时正常通过；如果发现锁，会以 `warn` 显示锁路径、pid、创建时间和安全清理提示。
 
 需要先查看发布计划但不修改服务器时：
 
@@ -359,13 +364,16 @@ export SSH_RELEASE_PASSWORD='your-password'
 - `tar`：本地打包发布内容。
 - `ssh`：执行远端目录、解压、软链接、列表和检查命令。
 - `scp`：上传压缩包和逐文件回退上传。
-- `sha256sum` 或 `shasum`：发布后校验远端 `manifest.json` hash。
 - `sshpass`：仅密码登录时需要；私钥登录不需要。
 
 在 macOS 上打包时会禁用 AppleDouble 和扩展属性元数据，避免把 `._*` 文件发布到 Linux 服务器。
 
+远端需要可运行 `sha256sum` 或 `shasum`，用于校验 `manifest.json` hash。
+
 远端 `tar` 是可选能力，不可用时会按配置回退逐文件上传。
 
+Windows、macOS、Linux 和 CI 的依赖差异见 [docs/platform-requirements.md](https://github.com/JackEngineer/ssh-release/blob/main/docs/platform-requirements.md)。
+
 ## 开发命令
 
 ```bash
@@ -412,6 +420,10 @@ GitHub Actions 发布模板见 [docs/github-actions.md](https://github.com/JackE
 
 失败恢复指南见 [docs/recovery.md](https://github.com/JackEngineer/ssh-release/blob/main/docs/recovery.md)。
 
+首次发布指南见 [docs/quick-start.md](https://github.com/JackEngineer/ssh-release/blob/main/docs/quick-start.md)。
+
+平台依赖说明见 [docs/platform-requirements.md](https://github.com/JackEngineer/ssh-release/blob/main/docs/platform-requirements.md)。
+
 版本变更见 [CHANGELOG.md](https://github.com/JackEngineer/ssh-release/blob/main/CHANGELOG.md)。
 
 ## 项目结构
@@ -458,6 +470,8 @@ tests/
 docs/
 ├── contracts.md
 ├── github-actions.md
+├── platform-requirements.md
+├── quick-start.md
 ├── recovery.md
 ├── release-checklist.md
 └── superpowers/specs/2026-06-25-ssh-release-design.md
@@ -480,6 +494,7 @@ docs/
 - 发布和回滚锁获取、释放和锁冲突拦截。
 - 发布 manifest 生成、上传和远端 hash 校验。
 - `doctor` 远端锁状态检查和安全清理提示。
+- `doctor` 本地命令和远端 hash 检查。
 - `unlock` 显式确认路径后删除远端锁。
 - 远端 `tar` 失败后的逐文件上传回退。
 - 远程版本列表读取和当前版本标记。

package/dist/cli.js

@@ -54,6 +54,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 return 0;
             }
             io.log(`已创建 ${parsed.configPath}`);
+            printInitNextSteps(parsed.configPath, io);
             return 0;
         }
         if (command === 'deploy') {
@@ -353,6 +354,13 @@ function printUnlockResult(result, io) {
     io.log('确认没有发布或回滚任务后再执行:');
     io.log(`ssh-release unlock --confirm ${result.lockPath}`);
 }
+function printInitNextSteps(configPath, io) {
+    io.log('下一步:');
+    io.log('1. 设置 SSH_RELEASE_HOST、SSH_RELEASE_USER，并选择密码或私钥认证。');
+    io.log('2. 确认 source.path 和 target.path 指向要发布的本地目录和远端目录。');
+    io.log(`3. 运行 ssh-release doctor --config ${configPath} 检查配置和服务器连接。`);
+    io.log(`4. 运行 ssh-release deploy --plan --config ${configPath} 预览发布计划。`);
+}
 function printJsonResult(command, result, exitCode, io) {
     io.log(JSON.stringify({
         ok: exitCode === 0,
@@ -415,6 +423,9 @@ function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function createErrorHint(command, error) {
+    if (error.includes('配置文件不存在')) {
+        return '先运行 ssh-release init 生成配置文件，再填写 source.path、server 和 target.path 后执行 ssh-release doctor。';
+    }
     if (error.includes('远程已有发布任务正在运行') || error.includes('.ssh-release.lock')) {
         return '先运行 ssh-release unlock 查看远端锁，确认没有发布或回滚任务后再按提示删除锁。';
     }
@@ -435,12 +446,14 @@ function createErrorHint(command, error) {
         || error.includes('manifest.json hash'))) {
         return '先运行 ssh-release list --json 和 ssh-release doctor --json，确认 current、版本目录、manifest 和远端锁状态。';
     }
+    if (error.includes('sshpass')) {
+        return '当前配置使用密码登录，本机需要安装 sshpass；macOS 可运行 brew install hudochenkov/sshpass/sshpass，Ubuntu/Debian 可运行 sudo apt-get install sshpass，Windows 和 CI 推荐改用私钥登录。';
+    }
     if (command
         && command !== 'init'
         && (error.includes('Permission denied')
             || error.includes('Connection timed out')
             || error.includes('Could not resolve hostname')
-            || error.includes('sshpass')
             || error.includes('SSH'))) {
         return '先运行 ssh-release doctor 检查 SSH 连接、认证信息和远端目录权限。';
     }

package/dist/doctor.js

@@ -1,6 +1,7 @@
 import { access } from 'node:fs/promises';
 import { loadConfigFile } from './config.js';
 import { readRemoteLockStatus } from './lock.js';
+import { runProcess } from './process.js';
 import { shellQuote } from './remote.js';
 export async function runDoctorFromFile(configPath, createClient) {
     let config;
@@ -32,8 +33,25 @@ export async function runDoctor(config, client, options = {}) {
         message: '配置字段有效',
     });
     await addSourcePathCheck(checks, config.source.path);
+    await addLocalDependencyChecks(checks, config, options.localCommandExists ?? defaultLocalCommandExists);
+    if (checks.some((check) => check.status === 'fail')) {
+        return {
+            ok: false,
+            checks,
+        };
+    }
     await addRemoteCheck(checks, 'SSH 连接', () => client.exec('true'), 'SSH 可连接');
     await addRemoteCheck(checks, '远程目录', () => client.exec(`mkdir -p ${shellQuote(config.target.path)} && test -w ${shellQuote(config.target.path)}`), '远程目录可创建且可写');
+    await addRemoteCheck(checks, '远端 hash', () => client.exec([
+        'if command -v sha256sum >/dev/null 2>&1; then',
+        'command -v sha256sum;',
+        'elif command -v shasum >/dev/null 2>&1; then',
+        'command -v shasum;',
+        'else',
+        'echo "远端缺少 sha256sum 或 shasum" >&2;',
+        'exit 1;',
+        'fi',
+    ].join(' ')), '远端 sha256sum 或 shasum 可用');
     await addRemoteLockCheck(checks, config, client);
     try {
         await client.exec('command -v tar');
@@ -127,6 +145,35 @@ async function addSourcePathCheck(checks, sourcePath) {
         });
     }
 }
+async function addLocalDependencyChecks(checks, config, localCommandExists) {
+    await addLocalCommandCheck(checks, 'tar', '本地 tar', localCommandExists);
+    await addLocalCommandCheck(checks, 'ssh', '本地 ssh', localCommandExists);
+    await addLocalCommandCheck(checks, 'scp', '本地 scp', localCommandExists);
+    if (config.server.password) {
+        await addLocalCommandCheck(checks, 'sshpass', '本地 sshpass', localCommandExists, '本地 sshpass 不可用；密码登录需要安装 sshpass，或改用私钥登录');
+    }
+}
+async function addLocalCommandCheck(checks, command, name, localCommandExists, missingMessage = `${name} 不可用；请安装后重试`) {
+    const exists = await localCommandExists(command);
+    checks.push({
+        name,
+        status: exists ? 'pass' : 'fail',
+        message: exists ? `${name} 可用` : missingMessage,
+    });
+}
+async function defaultLocalCommandExists(command) {
+    try {
+        if (process.platform === 'win32') {
+            await runProcess('where.exe', [command]);
+            return true;
+        }
+        await runProcess('sh', ['-c', `command -v ${shellQuote(command)} >/dev/null 2>&1`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function addRemoteCheck(checks, name, run, successMessage) {
     try {
         await run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ssh-release",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A general-purpose SSH file release CLI.",
   "type": "module",
   "bin": {