ssh-release 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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
+
+- 增强 npm 自动发布 workflow，发布后会验证 registry 版本和安装后的 CLI 入口。
+
 ## 1.0.1 - 2026-06-25
 
 ### Added

package/README.md

@@ -18,7 +18,11 @@
 - `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` 解压失败时回退逐文件上传。
@@ -179,6 +183,7 @@ ssh-release doctor
 
 ```bash
 ssh-release deploy --dry-run
+ssh-release deploy --plan
 ```
 
 执行发布：
@@ -187,9 +192,30 @@ ssh-release deploy --dry-run
 ssh-release deploy
 ```
 
-`release` 模式发布成功后会输出版本号、版本目录和 `current` 软链接路径。只有压缩包上传和解压完成后才切换 `current`。
+`deploy --dry-run` 和 `deploy --plan` 都不会连接远端或修改服务器，会预览：
 
-发布命令返回成功前会执行远端状态校验。`release` 模式会确认新版本目录存在、`current` 已指向新版本、远端锁已清理；`overwrite` 模式会确认目标目录存在、远端锁已清理。校验失败时发布命令返回失败，不会把结果标记为成功。
+- 将上传的本地来源和远端临时压缩包路径。
+- 将写入的远端 `manifest.json` 路径、文件数量和总字节数。
+- `release` 模式下将切换的 `current` 目标。
+- 将清理的远端临时压缩包，以及旧版本保留策略。
+- 发布后会执行的远端校验项。
+
+`release` 模式发布成功后会输出版本号、版本目录、`current` 软链接路径和远端 `manifest.json` 路径。只有压缩包上传、解压和发布清单上传完成后才切换 `current`。
+
+发布命令返回成功前会执行远端状态校验。`release` 模式会确认新版本目录存在、`current` 已指向新版本、发布清单 hash 匹配、远端锁已清理；`overwrite` 模式会确认目标目录存在、发布清单 hash 匹配、远端锁已清理。校验失败时发布命令返回失败，不会把结果标记为成功。
+
+`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 +253,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 +275,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 +286,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 +314,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` 中保留检查结果。
@@ -318,6 +359,7 @@ export SSH_RELEASE_PASSWORD='your-password'
 - `tar`：本地打包发布内容。
 - `ssh`：执行远端目录、解压、软链接、列表和检查命令。
 - `scp`：上传压缩包和逐文件回退上传。
+- `sha256sum` 或 `shasum`：发布后校验远端 `manifest.json` hash。
 - `sshpass`：仅密码登录时需要；私钥登录不需要。
 
 在 macOS 上打包时会禁用 AppleDouble 和扩展属性元数据，避免把 `._*` 文件发布到 Linux 服务器。
@@ -339,6 +381,7 @@ npm run build
 - `npm run build`：编译 `dist/`。
 - GitHub Actions 会在 `main` 推送和 Pull Request 上运行 `npm ci`、`lint`、`test` 和 `build`。
 - 推送 `v*` 标签会触发 npm 自动发布 workflow。发布使用 npm Trusted Publishing，不需要长期 `NPM_TOKEN`。
+- 发布 workflow 会在 `npm publish` 后验证 npm registry 的当前版本和 `latest`，并从 npm 重新安装当前版本做 CLI 烟测。
 
 ## 发布前检查
 
@@ -385,6 +428,7 @@ src/
 ├── doctor.ts
 ├── lock.ts
 ├── list.ts
+├── manifest.ts
 ├── package.ts
 ├── process.ts
 ├── remote.ts
@@ -402,6 +446,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
@@ -433,6 +478,7 @@ docs/
 - macOS AppleDouble 元数据排除。
 - `release` 和 `overwrite` 发布流程。
 - 发布和回滚锁获取、释放和锁冲突拦截。
+- 发布 manifest 生成、上传和远端 hash 校验。
 - `doctor` 远端锁状态检查和安全清理提示。
 - `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) {
@@ -72,7 +72,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 +121,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 +170,7 @@ function parseCliArgs(argv) {
             index += 1;
             continue;
         }
-        if (arg === '--dry-run') {
+        if (arg === '--dry-run' || arg === '--plan') {
             dryRun = true;
             continue;
         }
@@ -225,8 +230,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 +256,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 +287,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 +302,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) {
@@ -333,12 +368,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 +396,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 +414,38 @@ function readPackageVersion() {
 function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function createErrorHint(command, error) {
+    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 (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 连接、认证信息和远端目录权限。';
+    }
+    return undefined;
+}
 if (isCliEntrypoint(import.meta.url, process.argv[1])) {
     const exitCode = await runCli();
     process.exit(exitCode);

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.1",
+  "version": "1.1.0",
   "description": "A general-purpose SSH file release CLI.",
   "type": "module",
   "bin": {