ssh-release 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.3.0 - 2026-06-26
+
+### Added
+
+- 增加 `ssh-release rollback --json --progress`，回滚时按 NDJSON 输出 `lock`、`switch`、`cleanup`、`verify` 阶段状态。
+- 增强回滚后远端校验，成功结果会输出 `verified` 与 `verification`，确认目标版本目录、`current` 指向和远端锁清理状态。
+
+## 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,18 +11,20 @@
 已实现：
 
 - `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]`：回滚到上一个版本或指定版本。
 - `ssh-release unlock`：查看远端锁，并在显式确认锁路径后删除锁。
 - `--json`：输出单行 JSON，便于 CI/CD 解析。
 - `deploy --json --progress`：发布时输出 NDJSON 阶段进度，便于 CI/CD 展示实时状态。
+- `rollback --json --progress`：回滚时输出 NDJSON 阶段进度，便于 CI/CD 展示实时状态。
 - `deploy --plan`：不连接远端、不修改服务器，预览上传、切换、清理和校验计划。
 - `rollback --plan`：连接远端读取版本状态，但不修改服务器，预览回滚切换计划。
 - 失败下一步提示：常见锁、回滚目标、发布校验和 SSH 错误会提示下一步操作。
 - 发布 manifest：每次发布生成 `manifest.json`，记录版本、发布时间、本地来源、文件清单、文件大小和 SHA-256。
 - 发布后远端校验：确认版本目录或目标目录存在、`current` 已指向新版本、`manifest.json` hash 匹配、远端锁已清理。
+- 回滚后远端校验：确认目标版本目录存在、`current` 已指向目标版本、远端锁已清理。
 - `release` 模式：上传压缩包、远端解压、切换 `current`、清理旧版本。
 - `overwrite` 模式：直接覆盖发布到目标目录。
 - 远端 `tar` 解压失败时回退逐文件上传。
@@ -55,6 +57,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 +182,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、创建时间和安全清理提示。
 
 需要先查看发布计划但不修改服务器时：
 
@@ -280,6 +287,7 @@ ssh-release deploy --json --progress
 ssh-release doctor --json
 ssh-release list --json
 ssh-release rollback --json
+ssh-release rollback --json --progress
 ssh-release unlock --json
 ```
 
@@ -295,10 +303,11 @@ ssh-release unlock --json
 {"ok":false,"command":"deploy","error":"错误信息"}
 ```
 
-发布时需要持续读取阶段状态，可以使用：
+发布或回滚时需要持续读取阶段状态，可以使用：
 
 ```bash
 ssh-release deploy --json --progress
+ssh-release rollback --json --progress
 ```
 
 该模式会按行输出 NDJSON。进度事件先输出，最终结果最后输出：
@@ -309,9 +318,11 @@ ssh-release deploy --json --progress
 {"ok":true,"command":"deploy","result":{"mode":"release","version":"20260625-153000","verified":true}}
 ```
 
-`stage` 可能是 `source`、`lock`、`package`、`publish`、`cleanup`，`status` 可能是 `start`、`success`、`fail`。失败事件会包含 `error` 字段。
+`deploy` 的 `stage` 可能是 `source`、`lock`、`package`、`publish`、`cleanup`。
+`rollback` 的 `stage` 可能是 `lock`、`switch`、`cleanup`、`verify`。
+`status` 可能是 `start`、`success`、`fail`。失败事件会包含 `error` 字段。
 
-发布结果中的 `verification` 会列出已通过的远端校验项：
+发布和回滚结果中的 `verification` 会列出已通过的远端校验项：
 
 ```json
 {"verified":true,"verification":[{"name":"发布清单","status":"pass","message":"manifest.json 已上传并校验，文件数 12"}]}
@@ -359,13 +370,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 +426,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 +476,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 +500,7 @@ docs/
 - 发布和回滚锁获取、释放和锁冲突拦截。
 - 发布 manifest 生成、上传和远端 hash 校验。
 - `doctor` 远端锁状态检查和安全清理提示。
+- `doctor` 本地命令和远端 hash 检查。
 - `unlock` 显式确认路径后删除远端锁。
 - 远端 `tar` 失败后的逐文件上传回退。
 - 远程版本列表读取和当前版本标记。

package/dist/cli.js

@@ -6,7 +6,7 @@ import { CONFIG_FILE_NAME, loadConfigFile, writeConfigTemplate } from './config.
 import { runDoctorFromFile } from './doctor.js';
 import { listReleases } from './list.js';
 import { createDeployPlan, deploy, } from './release.js';
-import { createRollbackPlan, rollback } from './rollback.js';
+import { createRollbackPlan, rollback, } from './rollback.js';
 import { createRemoteClient } from './ssh.js';
 import { unlock } from './unlock.js';
 export function isCliEntrypoint(moduleUrl, argvEntry) {
@@ -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') {
@@ -72,7 +73,13 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             return 0;
         }
         if (command === 'rollback') {
-            const result = await handlers.rollback(args[0], { dryRun: parsed.dryRun });
+            const rollbackOptions = {
+                dryRun: parsed.dryRun,
+            };
+            if (parsed.json && parsed.progress) {
+                rollbackOptions.onProgress = (event) => printJsonProgress('rollback', event, io);
+            }
+            const result = await handlers.rollback(args[0], rollbackOptions);
             if (parsed.json) {
                 printJsonResult('rollback', result, 0, io);
                 return 0;
@@ -191,8 +198,8 @@ function parseCliArgs(argv) {
     if (progress && !json) {
         return createParsedError('--progress 需要配合 --json 使用', configPath, json);
     }
-    if (progress && args[0] && args[0] !== 'deploy') {
-        return createParsedError('--progress 仅支持 deploy 命令', configPath, json);
+    if (progress && args[0] && args[0] !== 'deploy' && args[0] !== 'rollback') {
+        return createParsedError('--progress 仅支持 deploy 或 rollback 命令', configPath, json);
     }
     return {
         args: args.slice(1),
@@ -235,7 +242,9 @@ function createDefaultHandlers(configPath) {
             if (options?.dryRun) {
                 return createRollbackPlan(config, createRemoteClient(config), version);
             }
-            return rollback(config, createRemoteClient(config), version);
+            return rollback(config, createRemoteClient(config), version, {
+                onProgress: options?.onProgress,
+            });
         },
         list: async () => {
             const config = await loadConfigFile(configPath);
@@ -316,6 +325,12 @@ function printRollbackResult(result, io) {
     }
     io.log(`已回滚到版本: ${result.version}`);
     io.log(`当前指向: ${result.currentSymlink}`);
+    if (result.verified) {
+        io.log('回滚校验通过');
+        for (const check of result.verification ?? []) {
+            io.log(`校验: ${check.name} - ${check.message}`);
+        }
+    }
     for (const warning of result.warnings) {
         io.log(`警告: ${warning}`);
     }
@@ -353,6 +368,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,
@@ -402,6 +424,7 @@ function createUsageText() {
   ssh-release rollback [version] [--config <path>]
   ssh-release rollback [version] --dry-run [--config <path>]
   ssh-release rollback [version] --plan [--config <path>]
+  ssh-release rollback [version] --json --progress [--config <path>]
   ssh-release unlock [--confirm <lock-path>] [--config <path>]
   ssh-release <command> --json
   ssh-release --help
@@ -415,6 +438,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 +461,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/dist/rollback.js

@@ -61,32 +61,35 @@ export async function createRollbackPlan(config, client, requestedVersion) {
         ],
     };
 }
-export async function rollback(config, client, requestedVersion) {
+export async function rollback(config, client, requestedVersion, options = {}) {
     if (config.deploy.mode === 'overwrite') {
         throw new Error('overwrite 模式不支持回滚');
     }
-    const releaseLock = await acquireRemoteLock(config, client, { createTargetPath: false });
+    const releaseLock = await withRollbackProgress(options, 'lock', () => acquireRemoteLock(config, client, { createTargetPath: false }));
     let result;
     let rollbackError;
+    let cleanupError;
     try {
-        const releasesPath = remoteJoin(config.target.path, config.target.releasesDir);
-        const currentSymlinkPath = remoteJoin(config.target.path, config.target.currentSymlink);
-        const releases = await readRemoteReleaseNames(client, releasesPath);
-        const currentVersion = await readCurrentVersion(client, currentSymlinkPath);
-        if (!currentVersion) {
-            throw new Error('当前版本不存在');
-        }
-        const targetVersion = selectRollbackTarget({
-            releases,
-            currentVersion,
-            requestedVersion,
+        result = await withRollbackProgress(options, 'switch', async () => {
+            const releasesPath = remoteJoin(config.target.path, config.target.releasesDir);
+            const currentSymlinkPath = remoteJoin(config.target.path, config.target.currentSymlink);
+            const releases = await readRemoteReleaseNames(client, releasesPath);
+            const currentVersion = await readCurrentVersion(client, currentSymlinkPath);
+            if (!currentVersion) {
+                throw new Error('当前版本不存在');
+            }
+            const targetVersion = selectRollbackTarget({
+                releases,
+                currentVersion,
+                requestedVersion,
+            });
+            await client.exec(`ln -sfn ${shellQuote(remoteJoin(config.target.releasesDir, targetVersion))} ${shellQuote(currentSymlinkPath)}`);
+            return {
+                version: targetVersion,
+                currentSymlink: currentSymlinkPath,
+                warnings: [],
+            };
         });
-        await client.exec(`ln -sfn ${shellQuote(remoteJoin(config.target.releasesDir, targetVersion))} ${shellQuote(currentSymlinkPath)}`);
-        result = {
-            version: targetVersion,
-            currentSymlink: currentSymlinkPath,
-            warnings: [],
-        };
         return result;
     }
     catch (error) {
@@ -94,20 +97,100 @@ export async function rollback(config, client, requestedVersion) {
         throw error;
     }
     finally {
-        try {
-            await releaseLock();
-        }
-        catch (error) {
-            const message = `远程发布锁清理失败: ${formatError(error)}`;
-            if (result) {
-                result.warnings.push(message);
+        await withRollbackProgress(options, 'cleanup', async () => {
+            try {
+                await releaseLock();
+            }
+            catch (error) {
+                const message = `远程回滚锁清理失败: ${formatError(error)}`;
+                if (result) {
+                    result.warnings.push(message);
+                }
+                else if (!rollbackError) {
+                    cleanupError = error;
+                }
             }
-            else if (!rollbackError) {
-                throw error;
+            if (cleanupError && !rollbackError) {
+                throw cleanupError;
             }
+        });
+        const rollbackResult = result;
+        if (rollbackResult && !rollbackError && !cleanupError) {
+            await withRollbackProgress(options, 'verify', async () => {
+                rollbackResult.verification = await verifyRollbackResult(config, client, rollbackResult);
+                rollbackResult.verified = true;
+            });
         }
     }
 }
+async function verifyRollbackResult(config, client, result) {
+    return [
+        await verifyRemoteDirectory(client, remoteJoin(config.target.path, config.target.releasesDir, result.version), '目标版本', '目标版本目录存在'),
+        await verifyCurrentSymlink(client, result.currentSymlink, remoteJoin(config.target.releasesDir, result.version)),
+        await verifyRemoteLockReleased(config, client),
+    ];
+}
+async function verifyRemoteDirectory(client, remotePath, name, successMessage) {
+    try {
+        await client.exec(`test -d ${shellQuote(remotePath)}`);
+    }
+    catch (error) {
+        throw new Error(`${name}校验失败: ${formatError(error)}`);
+    }
+    return {
+        name,
+        status: 'pass',
+        message: successMessage,
+    };
+}
+async function verifyCurrentSymlink(client, currentSymlinkPath, expectedTarget) {
+    let actualTarget;
+    try {
+        const result = await client.exec(`readlink ${shellQuote(currentSymlinkPath)}`);
+        actualTarget = result.stdout.trim();
+    }
+    catch (error) {
+        throw new Error(`current 校验失败: ${formatError(error)}`);
+    }
+    if (actualTarget !== expectedTarget) {
+        throw new Error(`current 未指向目标版本: 期望 ${expectedTarget}，实际 ${actualTarget || '空'}`);
+    }
+    return {
+        name: '当前版本',
+        status: 'pass',
+        message: 'current 已指向目标版本',
+    };
+}
+async function verifyRemoteLockReleased(config, client) {
+    const lockStatus = await readRemoteLockStatus(config, client);
+    if (lockStatus.locked) {
+        throw new Error(`回滚锁未清理: ${lockStatus.lockPath}`);
+    }
+    return {
+        name: '远端锁',
+        status: 'pass',
+        message: '回滚锁已清理',
+    };
+}
+async function withRollbackProgress(options, stage, run) {
+    await emitRollbackProgress(options, { stage, status: 'start' });
+    try {
+        const result = await run();
+        await emitRollbackProgress(options, { stage, status: 'success' });
+        return result;
+    }
+    catch (error) {
+        await emitRollbackProgress(options, {
+            stage,
+            status: 'fail',
+            error: formatError(error),
+        });
+        throw error;
+    }
+}
+async function emitRollbackProgress(options, event) {
+    await options.onProgress?.(event);
+}
 function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/package.json

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