ssh-release 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.6.0 - 2026-06-25
+
+### Added
+
+- 增加 `ssh-release deploy --json --progress`，发布时按 NDJSON 输出 `source`、`lock`、`package`、`publish`、`cleanup` 阶段状态，并在最后输出发布结果。
+
+## 0.5.0 - 2026-06-25
+
+### Added
+
+- 增加全局 `--json` 输出，支持 `deploy`、`doctor`、`list`、`rollback`、`unlock` 等命令输出单行结构化结果，便于 CI/CD 解析。
+
 ## 0.4.0 - 2026-06-25
 
 ### Added

package/README.md

@@ -16,6 +16,8 @@
 - `ssh-release list`：查看远程版本和当前版本。
 - `ssh-release rollback [version]`：回滚到上一个版本或指定版本。
 - `ssh-release unlock`：查看远端锁，并在显式确认锁路径后删除锁。
+- `--json`：输出单行 JSON，便于 CI/CD 解析。
+- `deploy --json --progress`：发布时输出 NDJSON 阶段进度，便于 CI/CD 展示实时状态。
 - `release` 模式：上传压缩包、远端解压、切换 `current`、清理旧版本。
 - `overwrite` 模式：直接覆盖发布到目标目录。
 - 远端 `tar` 解压失败时回退逐文件上传。
@@ -224,6 +226,49 @@ ssh-release rollback 20260625-150000
 
 `overwrite` 模式没有版本列表，也不支持回滚。
 
+## JSON 输出
+
+需要在自动化脚本中解析结果时，可以给命令增加 `--json`：
+
+```bash
+ssh-release deploy --dry-run --json
+ssh-release deploy --json --progress
+ssh-release doctor --json
+ssh-release list --json
+ssh-release rollback --json
+ssh-release unlock --json
+```
+
+成功时输出单行 JSON：
+
+```json
+{"ok":true,"command":"deploy","result":{"dryRun":true,"mode":"release"}}
+```
+
+命令执行失败时输出：
+
+```json
+{"ok":false,"command":"deploy","error":"错误信息"}
+```
+
+发布时需要持续读取阶段状态，可以使用：
+
+```bash
+ssh-release deploy --json --progress
+```
+
+该模式会按行输出 NDJSON。进度事件先输出，最终结果最后输出：
+
+```json
+{"ok":true,"command":"deploy","event":"progress","stage":"package","status":"start"}
+{"ok":true,"command":"deploy","event":"progress","stage":"package","status":"success"}
+{"ok":true,"command":"deploy","result":{"mode":"release","version":"20260625-153000"}}
+```
+
+`stage` 可能是 `source`、`lock`、`package`、`publish`、`cleanup`，`status` 可能是 `start`、`success`、`fail`。失败事件会包含 `error` 字段。
+
+`doctor` 检查失败、`unlock` 发现锁但未删除时会返回非零退出码，并在 JSON 的 `result` 中保留检查结果。
+
 ## 安全边界
 
 配置模板不包含真实 IP、密码或生产路径。
@@ -363,6 +408,7 @@ docs/
 - 危险远程路径拒绝。
 - 发布模式和压缩格式校验。
 - CLI 命令分发。
+- CLI JSON 输出。
 - 本地 `.tgz` 打包和排除项。
 - macOS AppleDouble 元数据排除。
 - `release` 和 `overwrite` 发布流程。

package/dist/cli.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { CONFIG_FILE_NAME, loadConfigFile, writeConfigTemplate } from './config.js';
 import { runDoctorFromFile } from './doctor.js';
 import { listReleases } from './list.js';
-import { createDeployPlan, deploy } from './release.js';
+import { createDeployPlan, deploy, } from './release.js';
 import { rollback } from './rollback.js';
 import { createRemoteClient } from './ssh.js';
 import { unlock } from './unlock.js';
@@ -19,15 +19,28 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
     const io = options.io ?? console;
     const parsed = parseCliArgs(argv);
     if (parsed.error) {
+        if (parsed.json) {
+            printJsonError(parsed.command, parsed.error, io);
+            return 1;
+        }
         io.error(parsed.error);
         return 1;
     }
     if (parsed.help) {
+        if (parsed.json) {
+            printJsonResult('help', { usage: createUsageText() }, 0, io);
+            return 0;
+        }
         printUsage(io);
         return 0;
     }
     if (parsed.version) {
-        io.log(readPackageVersion());
+        const version = readPackageVersion();
+        if (parsed.json) {
+            printJsonResult('version', { version }, 0, io);
+            return 0;
+        }
+        io.log(version);
         return 0;
     }
     const handlers = options.handlers ?? createDefaultHandlers(parsed.configPath);
@@ -36,35 +49,82 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
     try {
         if (command === 'init') {
             await handlers.init();
+            if (parsed.json) {
+                printJsonResult('init', { configPath: parsed.configPath }, 0, io);
+                return 0;
+            }
             io.log(`已创建 ${parsed.configPath}`);
             return 0;
         }
         if (command === 'deploy') {
-            printDeployResult(await handlers.deploy({ dryRun: parsed.dryRun }), io);
+            const deployOptions = {
+                dryRun: parsed.dryRun,
+            };
+            if (parsed.json && parsed.progress) {
+                deployOptions.onProgress = (event) => printJsonProgress('deploy', event, io);
+            }
+            const result = await handlers.deploy(deployOptions);
+            if (parsed.json) {
+                printJsonResult('deploy', result, 0, io);
+                return 0;
+            }
+            printDeployResult(result, io);
             return 0;
         }
         if (command === 'rollback') {
-            printRollbackResult(await handlers.rollback(args[0]), io);
+            const result = await handlers.rollback(args[0]);
+            if (parsed.json) {
+                printJsonResult('rollback', result, 0, io);
+                return 0;
+            }
+            printRollbackResult(result, io);
             return 0;
         }
         if (command === 'list') {
-            printListResult(await handlers.list(), io);
+            const result = await handlers.list();
+            if (parsed.json) {
+                printJsonResult('list', result, 0, io);
+                return 0;
+            }
+            printListResult(result, io);
             return 0;
         }
         if (command === 'doctor') {
             const report = await handlers.doctor();
+            const exitCode = report.ok ? 0 : 1;
+            if (parsed.json) {
+                printJsonResult('doctor', report, exitCode, io);
+                return exitCode;
+            }
             printDoctorReport(report, io);
-            return report.ok ? 0 : 1;
+            return exitCode;
         }
         if (command === 'unlock') {
             const result = await handlers.unlock({ confirmPath: parsed.confirmPath });
+            const exitCode = result.locked && !result.removed ? 1 : 0;
+            if (parsed.json) {
+                printJsonResult('unlock', result, exitCode, io);
+                return exitCode;
+            }
             printUnlockResult(result, io);
-            return result.locked && !result.removed ? 1 : 0;
+            return exitCode;
+        }
+        if (parsed.json) {
+            if (!command) {
+                printJsonResult('help', { usage: createUsageText() }, 0, io);
+                return 0;
+            }
+            printJsonError(command, `未知命令: ${command}`, io);
+            return 1;
         }
         printUsage(io);
         return command ? 1 : 0;
     }
     catch (error) {
+        if (parsed.json) {
+            printJsonError(command, formatError(error), io);
+            return 1;
+        }
         io.error(error instanceof Error ? error.message : String(error));
         return 1;
     }
@@ -75,6 +135,8 @@ function parseCliArgs(argv) {
     let configPath = CONFIG_FILE_NAME;
     let dryRun = false;
     let help = false;
+    let json = false;
+    let progress = false;
     let version = false;
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -86,10 +148,18 @@ function parseCliArgs(argv) {
             version = true;
             continue;
         }
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--progress') {
+            progress = true;
+            continue;
+        }
         if (arg === '--config' || arg === '-c') {
             const value = argv[index + 1];
             if (!value || value.startsWith('-')) {
-                return createParsedError('--config 需要配置文件路径', configPath);
+                return createParsedError('--config 需要配置文件路径', configPath, json);
             }
             configPath = value;
             index += 1;
@@ -102,17 +172,23 @@ function parseCliArgs(argv) {
         if (arg === '--confirm') {
             const value = argv[index + 1];
             if (!value || value.startsWith('-')) {
-                return createParsedError('--confirm 需要远端锁路径', configPath);
+                return createParsedError('--confirm 需要远端锁路径', configPath, json);
             }
             confirmPath = value;
             index += 1;
             continue;
         }
         if (arg.startsWith('-')) {
-            return createParsedError(`未知选项: ${arg}`, configPath);
+            return createParsedError(`未知选项: ${arg}`, configPath, json);
         }
         args.push(arg);
     }
+    if (progress && !json) {
+        return createParsedError('--progress 需要配合 --json 使用', configPath, json);
+    }
+    if (progress && args[0] && args[0] !== 'deploy') {
+        return createParsedError('--progress 仅支持 deploy 命令', configPath, json);
+    }
     return {
         args: args.slice(1),
         command: args[0],
@@ -120,16 +196,20 @@ function parseCliArgs(argv) {
         configPath,
         dryRun,
         help,
+        json,
+        progress,
         version,
     };
 }
-function createParsedError(error, configPath) {
+function createParsedError(error, configPath, json = false) {
     return {
         args: [],
         configPath,
         dryRun: false,
         error,
         help: false,
+        json,
+        progress: false,
         version: false,
     };
 }
@@ -141,7 +221,9 @@ function createDefaultHandlers(configPath) {
             if (options?.dryRun) {
                 return createDeployPlan(config);
             }
-            return deploy(config, createRemoteClient(config));
+            return deploy(config, createRemoteClient(config), {
+                onProgress: options?.onProgress,
+            });
         },
         rollback: async (version) => {
             const config = await loadConfigFile(configPath);
@@ -230,6 +312,28 @@ function printUnlockResult(result, io) {
     io.log('确认没有发布或回滚任务后再执行:');
     io.log(`ssh-release unlock --confirm ${result.lockPath}`);
 }
+function printJsonResult(command, result, exitCode, io) {
+    io.log(JSON.stringify({
+        ok: exitCode === 0,
+        command,
+        result,
+    }));
+}
+function printJsonProgress(command, event, io) {
+    io.log(JSON.stringify({
+        ok: true,
+        command,
+        event: 'progress',
+        ...event,
+    }));
+}
+function printJsonError(command, error, io) {
+    io.log(JSON.stringify({
+        ok: false,
+        command,
+        error,
+    }));
+}
 function toRealPath(filePath) {
     try {
         return realpathSync(filePath);
@@ -239,21 +343,29 @@ function toRealPath(filePath) {
     }
 }
 function printUsage(io) {
-    io.log(`用法:
+    io.log(createUsageText());
+}
+function createUsageText() {
+    return `用法:
   ssh-release init [--config <path>]
   ssh-release doctor [--config <path>]
   ssh-release deploy [--config <path>]
   ssh-release deploy --dry-run [--config <path>]
+  ssh-release deploy --json --progress [--config <path>]
   ssh-release list [--config <path>]
   ssh-release rollback [version] [--config <path>]
   ssh-release unlock [--confirm <lock-path>] [--config <path>]
+  ssh-release <command> --json
   ssh-release --help
-  ssh-release --version`);
+  ssh-release --version`;
 }
 function readPackageVersion() {
     const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
     return packageJson.version ?? '0.0.0';
 }
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 if (isCliEntrypoint(import.meta.url, process.argv[1])) {
     const exitCode = await runCli();
     process.exit(exitCode);

package/dist/release.js

@@ -28,25 +28,25 @@ function pad(value) {
     return value.toString().padStart(2, '0');
 }
 export async function deploy(config, client, options = {}) {
-    await ensureSourceExists(config.source.path);
+    await withDeployProgress(options, 'source', () => ensureSourceExists(config.source.path));
     const versionName = createVersionName(options.now ?? new Date());
     const packageFactory = options.createPackage ?? createReleasePackage;
-    const releaseLock = await acquireRemoteLock(config, client);
+    const releaseLock = await withDeployProgress(options, 'lock', () => acquireRemoteLock(config, client));
     let releasePackage;
     let result;
     let deployError;
     let cleanupError;
     try {
-        releasePackage = await packageFactory({
+        releasePackage = await withDeployProgress(options, 'package', () => packageFactory({
             sourcePath: config.source.path,
             exclude: config.source.exclude,
             versionName,
-        });
+        }));
         if (config.deploy.mode === 'overwrite') {
-            result = await deployOverwrite(config, client, releasePackage, versionName);
+            result = await withDeployProgress(options, 'publish', () => deployOverwrite(config, client, releasePackage, versionName));
             return result;
         }
-        result = await deployRelease(config, client, releasePackage, versionName);
+        result = await withDeployProgress(options, 'publish', () => deployRelease(config, client, releasePackage, versionName));
         return result;
     }
     catch (error) {
@@ -54,29 +54,31 @@ export async function deploy(config, client, options = {}) {
         throw error;
     }
     finally {
-        if (releasePackage) {
+        await withDeployProgress(options, 'cleanup', async () => {
+            if (releasePackage) {
+                try {
+                    await releasePackage.cleanup();
+                }
+                catch (error) {
+                    cleanupError = error;
+                }
+            }
             try {
-                await releasePackage.cleanup();
+                await releaseLock();
             }
             catch (error) {
-                cleanupError = error;
+                const message = `远程发布锁清理失败: ${formatError(error)}`;
+                if (result) {
+                    result.warnings.push(message);
+                }
+                else if (!deployError && !cleanupError) {
+                    cleanupError = error;
+                }
             }
-        }
-        try {
-            await releaseLock();
-        }
-        catch (error) {
-            const message = `远程发布锁清理失败: ${formatError(error)}`;
-            if (result) {
-                result.warnings.push(message);
+            if (cleanupError && !deployError) {
+                throw cleanupError;
             }
-            else if (!deployError && !cleanupError) {
-                cleanupError = error;
-            }
-        }
-        if (cleanupError && !deployError) {
-            throw cleanupError;
-        }
+        });
     }
 }
 export async function createDeployPlan(config, options = {}) {
@@ -191,3 +193,22 @@ async function ensureSourceExists(sourcePath) {
 function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+async function withDeployProgress(options, stage, run) {
+    await emitDeployProgress(options, { stage, status: 'start' });
+    try {
+        const result = await run();
+        await emitDeployProgress(options, { stage, status: 'success' });
+        return result;
+    }
+    catch (error) {
+        await emitDeployProgress(options, {
+            stage,
+            status: 'fail',
+            error: formatError(error),
+        });
+        throw error;
+    }
+}
+async function emitDeployProgress(options, event) {
+    await options.onProgress?.(event);
+}

package/package.json

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