ssh-release 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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,7 @@
 - `ssh-release list`：查看远程版本和当前版本。
 - `ssh-release rollback [version]`：回滚到上一个版本或指定版本。
 - `ssh-release unlock`：查看远端锁，并在显式确认锁路径后删除锁。
+- `--json`：输出单行 JSON，便于 CI/CD 解析。
 - `release` 模式：上传压缩包、远端解压、切换 `current`、清理旧版本。
 - `overwrite` 模式：直接覆盖发布到目标目录。
 - 远端 `tar` 解压失败时回退逐文件上传。
@@ -224,6 +225,32 @@ ssh-release rollback 20260625-150000
 
 `overwrite` 模式没有版本列表，也不支持回滚。
 
+## JSON 输出
+
+需要在自动化脚本中解析结果时，可以给命令增加 `--json`：
+
+```bash
+ssh-release deploy --dry-run --json
+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":"错误信息"}
+```
+
+`doctor` 检查失败、`unlock` 发现锁但未删除时会返回非零退出码，并在 JSON 的 `result` 中保留检查结果。
+
 ## 安全边界
 
 配置模板不包含真实 IP、密码或生产路径。
@@ -363,6 +390,7 @@ docs/
 - 危险远程路径拒绝。
 - 发布模式和压缩格式校验。
 - CLI 命令分发。
+- CLI JSON 输出。
 - 本地 `.tgz` 打包和排除项。
 - macOS AppleDouble 元数据排除。
 - `release` 和 `overwrite` 发布流程。

package/dist/cli.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,76 @@ 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 result = await handlers.deploy({ dryRun: parsed.dryRun });
+            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 +129,7 @@ function parseCliArgs(argv) {
     let configPath = CONFIG_FILE_NAME;
     let dryRun = false;
     let help = false;
+    let json = false;
     let version = false;
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -86,10 +141,14 @@ function parseCliArgs(argv) {
             version = true;
             continue;
         }
+        if (arg === '--json') {
+            json = 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,14 +161,14 @@ 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);
     }
@@ -120,16 +179,18 @@ function parseCliArgs(argv) {
         configPath,
         dryRun,
         help,
+        json,
         version,
     };
 }
-function createParsedError(error, configPath) {
+function createParsedError(error, configPath, json = false) {
     return {
         args: [],
         configPath,
         dryRun: false,
         error,
         help: false,
+        json,
         version: false,
     };
 }
@@ -230,6 +291,20 @@ 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 printJsonError(command, error, io) {
+    io.log(JSON.stringify({
+        ok: false,
+        command,
+        error,
+    }));
+}
 function toRealPath(filePath) {
     try {
         return realpathSync(filePath);
@@ -239,7 +314,10 @@ 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>]
@@ -247,13 +325,17 @@ function printUsage(io) {
   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/package.json

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