ssh-release 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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
+
+- 增强 `deploy --dry-run` 并新增 `deploy --plan`，预览上传、manifest、切换、清理和校验计划。
+- 增强 `rollback --dry-run` 并新增 `rollback --plan`，预览回滚目标、`current` 切换和校验项。
+- 增加常见失败的下一步提示，覆盖远端锁、回滚目标、发布校验和 SSH 连接错误。
+- 增加发布 manifest，发布时生成并上传 `manifest.json`，记录文件清单、大小和 SHA-256。
+- 增强发布后校验，远端 `manifest.json` 会进行 hash 校验。
+
 ## 1.0.2 - 2026-06-26
 
 ### Changed

package/README.md

@@ -11,14 +11,18 @@
 已实现：
 
 - `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 展示实时状态。
-- 发布后远端校验：确认版本目录或目标目录存在、`current` 已指向新版本、远端锁已清理。
+- `deploy --plan`：不连接远端、不修改服务器，预览上传、切换、清理和校验计划。
+- `rollback --plan`：连接远端读取版本状态，但不修改服务器，预览回滚切换计划。
+- 失败下一步提示：常见锁、回滚目标、发布校验和 SSH 错误会提示下一步操作。
+- 发布 manifest：每次发布生成 `manifest.json`，记录版本、发布时间、本地来源、文件清单、文件大小和 SHA-256。
+- 发布后远端校验：确认版本目录或目标目录存在、`current` 已指向新版本、`manifest.json` hash 匹配、远端锁已清理。
 - `release` 模式：上传压缩包、远端解压、切换 `current`、清理旧版本。
 - `overwrite` 模式：直接覆盖发布到目标目录。
 - 远端 `tar` 解压失败时回退逐文件上传。
@@ -51,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
@@ -173,12 +180,15 @@ 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、创建时间和安全清理提示。
 
 需要先查看发布计划但不修改服务器时：
 
 ```bash
 ssh-release deploy --dry-run
+ssh-release deploy --plan
 ```
 
 执行发布：
@@ -187,9 +197,30 @@ ssh-release deploy --dry-run
 ssh-release deploy
 ```
 
-`release` 模式发布成功后会输出版本号、版本目录和 `current` 软链接路径。只有压缩包上传和解压完成后才切换 `current`。
+`deploy --dry-run` 和 `deploy --plan` 都不会连接远端或修改服务器，会预览：
+
+- 将上传的本地来源和远端临时压缩包路径。
+- 将写入的远端 `manifest.json` 路径、文件数量和总字节数。
+- `release` 模式下将切换的 `current` 目标。
+- 将清理的远端临时压缩包，以及旧版本保留策略。
+- 发布后会执行的远端校验项。
+
+`release` 模式发布成功后会输出版本号、版本目录、`current` 软链接路径和远端 `manifest.json` 路径。只有压缩包上传、解压和发布清单上传完成后才切换 `current`。
+
+发布命令返回成功前会执行远端状态校验。`release` 模式会确认新版本目录存在、`current` 已指向新版本、发布清单 hash 匹配、远端锁已清理；`overwrite` 模式会确认目标目录存在、发布清单 hash 匹配、远端锁已清理。校验失败时发布命令返回失败，不会把结果标记为成功。
 
-发布命令返回成功前会执行远端状态校验。`release` 模式会确认新版本目录存在、`current` 已指向新版本、远端锁已清理；`overwrite` 模式会确认目标目录存在、远端锁已清理。校验失败时发布命令返回失败，不会把结果标记为成功。
+`manifest.json` 会写入发布目标目录：
+
+- `release` 模式：`<target.path>/<releasesDir>/<version>/manifest.json`
+- `overwrite` 模式：`<target.path>/manifest.json`
+
+清单内容包含：
+
+- `version`：本次发布版本号。
+- `createdAt`：发布时间。
+- `source`：配置中的本地来源路径、来源类型和排除规则。
+- `files`：每个文件的相对路径、字节数和 SHA-256。
+- `totals`：文件数量和总字节数。
 
 如果远端已有 `.ssh-release.lock`，说明同一目标目录可能正在发布或回滚，工具会停止在修改远端状态之前。
 
@@ -227,6 +258,20 @@ ssh-release rollback
 ssh-release rollback 20260625-150000
 ```
 
+需要先查看回滚计划但不切换 `current` 时：
+
+```bash
+ssh-release rollback [version] --dry-run
+ssh-release rollback [version] --plan
+```
+
+`rollback --dry-run` 和 `rollback --plan` 会连接远端读取锁状态、版本列表和当前版本，但不会创建锁、不会切换 `current`、不会删除任何版本目录。预览会显示：
+
+- 当前版本和目标版本。
+- 将切换的 `current` 路径和目标。
+- 回滚不会删除版本目录。
+- 实际回滚前需要满足的校验项。
+
 `overwrite` 模式没有版本列表，也不支持回滚。
 
 ## JSON 输出
@@ -235,6 +280,7 @@ ssh-release rollback 20260625-150000
 
 ```bash
 ssh-release deploy --dry-run --json
+ssh-release deploy --plan --json
 ssh-release deploy --json --progress
 ssh-release doctor --json
 ssh-release list --json
@@ -245,7 +291,7 @@ ssh-release unlock --json
 成功时输出单行 JSON：
 
 ```json
-{"ok":true,"command":"deploy","result":{"mode":"release","version":"20260625-153000","verified":true}}
+{"ok":true,"command":"deploy","result":{"mode":"release","version":"20260625-153000","manifest":{"remotePath":"/var/www/my-app/releases/20260625-153000/manifest.json","fileCount":12,"totalBytes":34567,"sha256":"..."},"verified":true}}
 ```
 
 命令执行失败时输出：
@@ -273,7 +319,7 @@ ssh-release deploy --json --progress
 发布结果中的 `verification` 会列出已通过的远端校验项：
 
 ```json
-{"verified":true,"verification":[{"name":"当前版本","status":"pass","message":"current 已指向新版本"}]}
+{"verified":true,"verification":[{"name":"发布清单","status":"pass","message":"manifest.json 已上传并校验，文件数 12"}]}
 ```
 
 `doctor` 检查失败、`unlock` 发现锁但未删除时会返回非零退出码，并在 JSON 的 `result` 中保留检查结果。
@@ -322,8 +368,12 @@ export SSH_RELEASE_PASSWORD='your-password'
 
 在 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
@@ -370,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)。
 
 ## 项目结构
@@ -386,6 +440,7 @@ src/
 ├── doctor.ts
 ├── lock.ts
 ├── list.ts
+├── manifest.ts
 ├── package.ts
 ├── process.ts
 ├── remote.ts
@@ -403,6 +458,7 @@ tests/
 ├── deploy.test.ts
 ├── e2e.test.ts
 ├── list-doctor.test.ts
+├── manifest.test.ts
 ├── package-json.test.ts
 ├── package.test.ts
 ├── release.test.ts
@@ -414,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
@@ -434,7 +492,9 @@ docs/
 - macOS AppleDouble 元数据排除。
 - `release` 和 `overwrite` 发布流程。
 - 发布和回滚锁获取、释放和锁冲突拦截。
+- 发布 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 { 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,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             return 0;
         }
         if (command === 'rollback') {
-            const result = await handlers.rollback(args[0]);
+            const result = await handlers.rollback(args[0], { dryRun: parsed.dryRun });
             if (parsed.json) {
                 printJsonResult('rollback', result, 0, io);
                 return 0;
@@ -121,11 +122,16 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         return command ? 1 : 0;
     }
     catch (error) {
+        const errorMessage = formatError(error);
+        const hint = createErrorHint(command, errorMessage);
         if (parsed.json) {
-            printJsonError(command, formatError(error), io);
+            printJsonError(command, errorMessage, io, hint);
             return 1;
         }
-        io.error(error instanceof Error ? error.message : String(error));
+        io.error(errorMessage);
+        if (hint) {
+            io.error(`下一步: ${hint}`);
+        }
         return 1;
     }
 }
@@ -165,7 +171,7 @@ function parseCliArgs(argv) {
             index += 1;
             continue;
         }
-        if (arg === '--dry-run') {
+        if (arg === '--dry-run' || arg === '--plan') {
             dryRun = true;
             continue;
         }
@@ -225,8 +231,11 @@ function createDefaultHandlers(configPath) {
                 onProgress: options?.onProgress,
             });
         },
-        rollback: async (version) => {
+        rollback: async (version, options) => {
             const config = await loadConfigFile(configPath);
+            if (options?.dryRun) {
+                return createRollbackPlan(config, createRemoteClient(config), version);
+            }
             return rollback(config, createRemoteClient(config), version);
         },
         list: async () => {
@@ -248,12 +257,23 @@ function printDeployResult(result, io) {
         io.log(`模式: ${result.mode}`);
         io.log(`源路径: ${result.sourcePath}`);
         io.log(`目标目录: ${result.targetPath}`);
+        io.log(`计划上传: ${result.upload.sourcePath} -> ${result.upload.archivePath}`);
+        io.log(`计划清单: ${result.upload.manifestPath}`);
+        io.log(`计划文件: ${result.upload.fileCount} 个，${result.upload.totalBytes} 字节`);
         if (result.version) {
             io.log(`计划版本: ${result.version}`);
         }
-        if (result.currentSymlink) {
+        if (result.switch) {
+            io.log(`计划切换: ${result.switch.currentSymlink} -> ${result.switch.target}`);
+        }
+        else if (result.currentSymlink) {
             io.log(`计划切换: ${result.currentSymlink}`);
         }
+        io.log(`计划清理: ${result.cleanup.tempArchivePath}`);
+        io.log(`版本保留: ${result.cleanup.oldReleases}`);
+        for (const verification of result.verification) {
+            io.log(`计划校验: ${verification}`);
+        }
         return;
     }
     if (result.mode === 'release') {
@@ -268,6 +288,10 @@ function printDeployResult(result, io) {
     if (result.usedFallback) {
         io.log('远端 tar 不可用或解压失败，已使用逐文件上传');
     }
+    if (result.manifest) {
+        io.log(`发布清单: ${result.manifest.remotePath}`);
+        io.log(`清单文件数: ${result.manifest.fileCount}`);
+    }
     if (result.verified) {
         io.log('远端校验通过');
         for (const check of result.verification ?? []) {
@@ -279,6 +303,18 @@ function printDeployResult(result, io) {
     }
 }
 function printRollbackResult(result, io) {
+    if ('dryRun' in result) {
+        io.log('回滚预检通过，不会修改远程服务器');
+        io.log(`当前版本: ${result.currentVersion}`);
+        io.log(`目标版本: ${result.version}`);
+        io.log(`目标目录: ${result.targetPath}`);
+        io.log(`计划切换: ${result.switch.currentSymlink}: ${result.switch.from} -> ${result.switch.target}`);
+        io.log(`计划清理: ${result.cleanup.oldReleases}`);
+        for (const verification of result.verification) {
+            io.log(`计划校验: ${verification}`);
+        }
+        return;
+    }
     io.log(`已回滚到版本: ${result.version}`);
     io.log(`当前指向: ${result.currentSymlink}`);
     for (const warning of result.warnings) {
@@ -318,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,
@@ -333,12 +376,16 @@ function printJsonProgress(command, event, io) {
         ...event,
     }));
 }
-function printJsonError(command, error, io) {
-    io.log(JSON.stringify({
+function printJsonError(command, error, io, hint) {
+    const payload = {
         ok: false,
         command,
         error,
-    }));
+    };
+    if (hint) {
+        payload.hint = hint;
+    }
+    io.log(JSON.stringify(payload));
 }
 function toRealPath(filePath) {
     try {
@@ -357,9 +404,12 @@ function createUsageText() {
   ssh-release doctor [--config <path>]
   ssh-release deploy [--config <path>]
   ssh-release deploy --dry-run [--config <path>]
+  ssh-release deploy --plan [--config <path>]
   ssh-release deploy --json --progress [--config <path>]
   ssh-release list [--config <path>]
   ssh-release rollback [version] [--config <path>]
+  ssh-release rollback [version] --dry-run [--config <path>]
+  ssh-release rollback [version] --plan [--config <path>]
   ssh-release unlock [--confirm <lock-path>] [--config <path>]
   ssh-release <command> --json
   ssh-release --help
@@ -372,6 +422,43 @@ function readPackageVersion() {
 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 查看远端锁，确认没有发布或回滚任务后再按提示删除锁。';
+    }
+    if (command === 'rollback') {
+        if (error.includes('回滚目标不存在')
+            || error.includes('没有可回滚版本')
+            || error.includes('当前版本不存在')) {
+            return '先运行 ssh-release list 查看当前版本和可用版本，再选择存在的版本回滚。';
+        }
+        if (error.includes('overwrite 模式不支持回滚')) {
+            return 'overwrite 模式没有版本目录；需要恢复内容时请重新发布正确的本地文件。';
+        }
+    }
+    if (command === 'deploy' && (error.includes('current 未指向新版本')
+        || error.includes('版本目录校验失败')
+        || error.includes('目标目录校验失败')
+        || error.includes('发布锁未清理')
+        || 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('SSH'))) {
+        return '先运行 ssh-release doctor 检查 SSH 连接、认证信息和远端目录权限。';
+    }
+    return undefined;
+}
 if (isCliEntrypoint(import.meta.url, process.argv[1])) {
     const exitCode = await runCli();
     process.exit(exitCode);

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/manifest.js

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+export async function createReleaseManifest(options) {
+    const sourceStat = await stat(options.sourcePath);
+    const files = sourceStat.isDirectory()
+        ? await collectDirectoryFiles(options.sourcePath, options.exclude)
+        : [await createManifestFileEntry(options.sourcePath, path.basename(options.sourcePath))];
+    const sortedFiles = files.sort((left, right) => left.path.localeCompare(right.path));
+    return {
+        version: options.version,
+        createdAt: options.createdAt.toISOString(),
+        source: {
+            path: options.sourcePath,
+            type: sourceStat.isDirectory() ? 'directory' : 'file',
+            exclude: options.exclude,
+        },
+        files: sortedFiles,
+        totals: {
+            files: sortedFiles.length,
+            bytes: sortedFiles.reduce((total, file) => total + file.size, 0),
+        },
+    };
+}
+export async function writeReleaseManifest(manifest) {
+    const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'ssh-release-manifest-'));
+    const localPath = path.join(tempDirectory, 'manifest.json');
+    const content = `${JSON.stringify(manifest, null, 2)}\n`;
+    await writeFile(localPath, content);
+    return {
+        localPath,
+        sha256: createHash('sha256').update(content).digest('hex'),
+        cleanup: async () => {
+            await rm(tempDirectory, { recursive: true, force: true });
+        },
+    };
+}
+async function collectDirectoryFiles(sourcePath, exclude, relativeDirectory = '') {
+    const entries = await readdir(path.join(sourcePath, relativeDirectory), { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const relativePath = toPosixPath(path.join(relativeDirectory, entry.name));
+        if (isExcluded(relativePath, exclude)) {
+            continue;
+        }
+        const localPath = path.join(sourcePath, relativePath);
+        if (entry.isDirectory()) {
+            files.push(...await collectDirectoryFiles(sourcePath, exclude, relativePath));
+            continue;
+        }
+        if (entry.isFile()) {
+            files.push(await createManifestFileEntry(localPath, relativePath));
+        }
+    }
+    return files;
+}
+async function createManifestFileEntry(localPath, relativePath) {
+    const content = await readFile(localPath);
+    return {
+        path: toPosixPath(relativePath),
+        size: content.byteLength,
+        sha256: createHash('sha256').update(content).digest('hex'),
+    };
+}
+function isExcluded(relativePath, exclude) {
+    const normalizedPath = toPosixPath(relativePath);
+    const pathSegments = normalizedPath.split('/');
+    return exclude.some((pattern) => {
+        const normalizedPattern = toPosixPath(pattern);
+        if (!normalizedPattern.includes('/')) {
+            return pathSegments.includes(normalizedPattern);
+        }
+        return wildcardMatch(normalizedPath, normalizedPattern)
+            || wildcardMatch(`./${normalizedPath}`, normalizedPattern);
+    });
+}
+function wildcardMatch(value, pattern) {
+    const escapedPattern = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replaceAll('*', '[^/]*');
+    return new RegExp(`^${escapedPattern}$`).test(value);
+}
+function toPosixPath(value) {
+    return value.split(path.sep).join(path.posix.sep);
+}

package/dist/release.js

@@ -1,5 +1,6 @@
 import { access } from 'node:fs/promises';
 import { createReleasePackage, } from './package.js';
+import { createReleaseManifest, writeReleaseManifest, } from './manifest.js';
 import { acquireRemoteLock, readRemoteLockStatus } from './lock.js';
 import { readRemoteReleaseNames, remoteJoin, shellQuote, } from './remote.js';
 export function createVersionName(date = new Date()) {
@@ -29,24 +30,46 @@ function pad(value) {
 }
 export async function deploy(config, client, options = {}) {
     await withDeployProgress(options, 'source', () => ensureSourceExists(config.source.path));
-    const versionName = createVersionName(options.now ?? new Date());
+    const releaseDate = options.now ?? new Date();
+    const versionName = createVersionName(releaseDate);
     const packageFactory = options.createPackage ?? createReleasePackage;
     const releaseLock = await withDeployProgress(options, 'lock', () => acquireRemoteLock(config, client));
     let releasePackage;
+    let manifest;
+    let manifestFile;
     let result;
     let deployError;
     let cleanupError;
     try {
-        releasePackage = await withDeployProgress(options, 'package', () => packageFactory({
-            sourcePath: config.source.path,
-            exclude: config.source.exclude,
-            versionName,
-        }));
+        releasePackage = await withDeployProgress(options, 'package', async () => {
+            const createdPackage = await packageFactory({
+                sourcePath: config.source.path,
+                exclude: config.source.exclude,
+                versionName,
+            });
+            try {
+                manifest = await createReleaseManifest({
+                    version: versionName,
+                    createdAt: releaseDate,
+                    sourcePath: config.source.path,
+                    exclude: config.source.exclude,
+                });
+                manifestFile = await writeReleaseManifest(manifest);
+                return createdPackage;
+            }
+            catch (error) {
+                await createdPackage.cleanup();
+                throw error;
+            }
+        });
+        if (!manifest || !manifestFile) {
+            throw new Error('发布清单生成失败');
+        }
         if (config.deploy.mode === 'overwrite') {
-            result = await withDeployProgress(options, 'publish', () => deployOverwrite(config, client, releasePackage, versionName));
+            result = await withDeployProgress(options, 'publish', () => deployOverwrite(config, client, releasePackage, manifest, manifestFile, versionName));
             return result;
         }
-        result = await withDeployProgress(options, 'publish', () => deployRelease(config, client, releasePackage, versionName));
+        result = await withDeployProgress(options, 'publish', () => deployRelease(config, client, releasePackage, manifest, manifestFile, versionName));
         return result;
     }
     catch (error) {
@@ -63,6 +86,14 @@ export async function deploy(config, client, options = {}) {
                     cleanupError = error;
                 }
             }
+            if (manifestFile) {
+                try {
+                    await manifestFile.cleanup();
+                }
+                catch (error) {
+                    cleanupError = error;
+                }
+            }
             try {
                 await releaseLock();
             }
@@ -87,35 +118,87 @@ export async function deploy(config, client, options = {}) {
 }
 export async function createDeployPlan(config, options = {}) {
     await ensureSourceExists(config.source.path);
+    const releaseDate = options.now ?? new Date();
+    const versionName = createVersionName(releaseDate);
+    const tempArchivePath = remoteJoin(config.target.path, config.target.tempDir, `${versionName}.tgz`);
+    const lockPath = remoteJoin(config.target.path, '.ssh-release.lock');
+    const manifest = await createReleaseManifest({
+        version: versionName,
+        createdAt: releaseDate,
+        sourcePath: config.source.path,
+        exclude: config.source.exclude,
+    });
     if (config.deploy.mode === 'overwrite') {
         return {
             dryRun: true,
             mode: 'overwrite',
             sourcePath: config.source.path,
             targetPath: config.target.path,
+            upload: createDeployPlanUpload(config, manifest, tempArchivePath, remoteJoin(config.target.path, 'manifest.json')),
+            cleanup: {
+                lockPath,
+                tempArchivePath,
+                keepReleases: config.deploy.keepReleases,
+                oldReleases: 'overwrite 模式不清理版本目录',
+            },
+            verification: [
+                '目标目录存在',
+                'manifest.json hash 匹配',
+                '远端锁已清理',
+            ],
         };
     }
-    const versionName = createVersionName(options.now ?? new Date());
     const releasesPath = remoteJoin(config.target.path, config.target.releasesDir);
+    const releasePath = remoteJoin(releasesPath, versionName);
+    const currentSymlink = remoteJoin(config.target.path, config.target.currentSymlink);
+    const switchTarget = remoteJoin(config.target.releasesDir, versionName);
     return {
         dryRun: true,
         mode: 'release',
         version: versionName,
         sourcePath: config.source.path,
-        targetPath: remoteJoin(releasesPath, versionName),
-        currentSymlink: remoteJoin(config.target.path, config.target.currentSymlink),
+        targetPath: releasePath,
+        currentSymlink,
+        upload: createDeployPlanUpload(config, manifest, tempArchivePath, remoteJoin(releasePath, 'manifest.json')),
+        switch: {
+            currentSymlink,
+            target: switchTarget,
+        },
+        cleanup: {
+            lockPath,
+            tempArchivePath,
+            keepReleases: config.deploy.keepReleases,
+            oldReleases: `发布成功后保留最新 ${config.deploy.keepReleases} 个版本，并保留当前版本`,
+        },
+        verification: [
+            '版本目录存在',
+            'current 指向新版本',
+            'manifest.json hash 匹配',
+            '远端锁已清理',
+        ],
     };
 }
-async function deployRelease(config, client, releasePackage, versionName) {
+function createDeployPlanUpload(config, manifest, archivePath, manifestPath) {
+    return {
+        sourcePath: config.source.path,
+        archivePath,
+        manifestPath,
+        fileCount: manifest.totals.files,
+        totalBytes: manifest.totals.bytes,
+    };
+}
+async function deployRelease(config, client, releasePackage, manifest, manifestFile, versionName) {
     const warnings = [];
     const releasesPath = remoteJoin(config.target.path, config.target.releasesDir);
     const releasePath = remoteJoin(releasesPath, versionName);
     const tempPath = remoteJoin(config.target.path, config.target.tempDir);
     const remoteArchivePath = remoteJoin(tempPath, `${versionName}.tgz`);
+    const remoteManifestPath = remoteJoin(releasePath, 'manifest.json');
     const currentSymlinkPath = remoteJoin(config.target.path, config.target.currentSymlink);
     await client.exec(`mkdir -p ${shellQuote(releasesPath)} ${shellQuote(tempPath)} ${shellQuote(releasePath)}`);
     await client.uploadFile(releasePackage.archivePath, remoteArchivePath);
     const usedFallback = await publishPackageToRemotePath(config, client, remoteArchivePath, releasePath, true);
+    await client.uploadFile(manifestFile.localPath, remoteManifestPath);
     await client.exec(`ln -sfn ${shellQuote(remoteJoin(config.target.releasesDir, versionName))} ${shellQuote(currentSymlinkPath)}`);
     await cleanupRemoteArchive(client, remoteArchivePath, warnings);
     await cleanupOldReleases(config, client, releasesPath, versionName, warnings);
@@ -125,24 +208,36 @@ async function deployRelease(config, client, releasePackage, versionName) {
         targetPath: releasePath,
         currentSymlink: currentSymlinkPath,
         usedFallback,
+        manifest: createDeployManifestSummary(manifest, manifestFile, remoteManifestPath),
         warnings,
     };
 }
-async function deployOverwrite(config, client, releasePackage, versionName) {
+async function deployOverwrite(config, client, releasePackage, manifest, manifestFile, versionName) {
     const warnings = [];
     const tempPath = remoteJoin(config.target.path, config.target.tempDir);
     const remoteArchivePath = remoteJoin(tempPath, `${versionName}.tgz`);
+    const remoteManifestPath = remoteJoin(config.target.path, 'manifest.json');
     await client.exec(`mkdir -p ${shellQuote(config.target.path)} ${shellQuote(tempPath)}`);
     await client.uploadFile(releasePackage.archivePath, remoteArchivePath);
     const usedFallback = await publishPackageToRemotePath(config, client, remoteArchivePath, config.target.path, false);
+    await client.uploadFile(manifestFile.localPath, remoteManifestPath);
     await cleanupRemoteArchive(client, remoteArchivePath, warnings);
     return {
         mode: 'overwrite',
         targetPath: config.target.path,
         usedFallback,
+        manifest: createDeployManifestSummary(manifest, manifestFile, remoteManifestPath),
         warnings,
     };
 }
+function createDeployManifestSummary(manifest, manifestFile, remotePath) {
+    return {
+        remotePath,
+        fileCount: manifest.totals.files,
+        totalBytes: manifest.totals.bytes,
+        sha256: manifestFile.sha256,
+    };
+}
 async function publishPackageToRemotePath(config, client, remoteArchivePath, remoteTargetPath, cleanBeforeFallback) {
     if (!config.deploy.preferTar) {
         await client.uploadDirectory(config.source.path, remoteTargetPath, config.source.exclude);
@@ -190,6 +285,7 @@ async function verifyDeployResult(config, client, result) {
     if (result.mode === 'overwrite') {
         return [
             await verifyRemoteDirectory(client, result.targetPath, '目标目录', '远端目标目录存在'),
+            ...await verifyOptionalManifest(client, result),
             await verifyRemoteLockReleased(config, client),
         ];
     }
@@ -199,9 +295,42 @@ async function verifyDeployResult(config, client, result) {
     return [
         await verifyRemoteDirectory(client, result.targetPath, '版本目录', '远端版本目录存在'),
         await verifyCurrentSymlink(client, result.currentSymlink, remoteJoin(config.target.releasesDir, result.version)),
+        ...await verifyOptionalManifest(client, result),
         await verifyRemoteLockReleased(config, client),
     ];
 }
+async function verifyOptionalManifest(client, result) {
+    if (!result.manifest) {
+        return [];
+    }
+    return [await verifyRemoteManifest(client, result.manifest)];
+}
+async function verifyRemoteManifest(client, manifest) {
+    try {
+        await client.exec(`test -f ${shellQuote(manifest.remotePath)}`);
+    }
+    catch (error) {
+        throw new Error(`manifest 校验失败: ${formatError(error)}`);
+    }
+    const actualHash = await readRemoteFileSha256(client, manifest.remotePath);
+    if (actualHash !== manifest.sha256) {
+        throw new Error(`manifest hash 不匹配: 期望 ${manifest.sha256}，实际 ${actualHash || '空'}`);
+    }
+    return {
+        name: '发布清单',
+        status: 'pass',
+        message: `manifest.json 已上传并校验，文件数 ${manifest.fileCount}`,
+    };
+}
+async function readRemoteFileSha256(client, remotePath) {
+    const quotedPath = shellQuote(remotePath);
+    const result = await client.exec(`if command -v sha256sum >/dev/null 2>&1; then sha256sum ${quotedPath} | awk '{print $1}'; elif command -v shasum >/dev/null 2>&1; then shasum -a 256 ${quotedPath} | awk '{print $1}'; else echo ''; fi`);
+    const hash = result.stdout.trim();
+    if (!hash) {
+        throw new Error('远端缺少 sha256sum 或 shasum，无法校验 manifest hash');
+    }
+    return hash;
+}
 async function verifyRemoteDirectory(client, remotePath, name, successMessage) {
     try {
         await client.exec(`test -d ${shellQuote(remotePath)}`);

package/dist/rollback.js

@@ -1,5 +1,5 @@
 import { readCurrentVersion, readRemoteReleaseNames, remoteJoin, shellQuote, } from './remote.js';
-import { acquireRemoteLock } from './lock.js';
+import { acquireRemoteLock, readRemoteLockStatus } from './lock.js';
 export function selectRollbackTarget(selection) {
     const releases = [...new Set(selection.releases)].sort();
     if (selection.requestedVersion) {
@@ -17,6 +17,50 @@ export function selectRollbackTarget(selection) {
     }
     return releases[currentIndex - 1];
 }
+export async function createRollbackPlan(config, client, requestedVersion) {
+    if (config.deploy.mode === 'overwrite') {
+        throw new Error('overwrite 模式不支持回滚');
+    }
+    const lockStatus = await readRemoteLockStatus(config, client);
+    if (lockStatus.locked) {
+        throw new Error(`远程已有发布任务正在运行，请确认后删除 ${lockStatus.lockPath}`);
+    }
+    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,
+    });
+    return {
+        dryRun: true,
+        mode: 'release',
+        version: targetVersion,
+        requestedVersion,
+        currentVersion,
+        targetPath: remoteJoin(releasesPath, targetVersion),
+        currentSymlink: currentSymlinkPath,
+        switch: {
+            currentSymlink: currentSymlinkPath,
+            from: remoteJoin(config.target.releasesDir, currentVersion),
+            target: remoteJoin(config.target.releasesDir, targetVersion),
+        },
+        cleanup: {
+            lockPath: lockStatus.lockPath,
+            oldReleases: '回滚只切换 current，不删除任何版本目录',
+        },
+        verification: [
+            '远端锁未占用',
+            '目标版本目录存在',
+            'current 将指向目标版本',
+        ],
+    };
+}
 export async function rollback(config, client, requestedVersion) {
     if (config.deploy.mode === 'overwrite') {
         throw new Error('overwrite 模式不支持回滚');

package/package.json

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