ssh-release 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.5.0 - 2026-06-25
+
+### Added
+
+- 增加全局 `--json` 输出，支持 `deploy`、`doctor`、`list`、`rollback`、`unlock` 等命令输出单行结构化结果，便于 CI/CD 解析。
+
+## 0.4.0 - 2026-06-25
+
+### Added
+
+- 增加 `ssh-release unlock` 安全解锁流程，默认只查看远端锁，必须传入匹配的 `--confirm <lock-path>` 才会删除锁目录。
+
 ## 0.3.0 - 2026-06-25
 
 ### Added

package/README.md

@@ -15,6 +15,8 @@
 - `ssh-release deploy`：发布本地文件或目录。
 - `ssh-release list`：查看远程版本和当前版本。
 - `ssh-release rollback [version]`：回滚到上一个版本或指定版本。
+- `ssh-release unlock`：查看远端锁，并在显式确认锁路径后删除锁。
+- `--json`：输出单行 JSON，便于 CI/CD 解析。
 - `release` 模式：上传压缩包、远端解压、切换 `current`、清理旧版本。
 - `overwrite` 模式：直接覆盖发布到目标目录。
 - 远端 `tar` 解压失败时回退逐文件上传。
@@ -55,6 +57,7 @@ npm run dev -- doctor
 npm run dev -- deploy
 npm run dev -- list
 npm run dev -- rollback
+npm run dev -- unlock
 ```
 
 构建 CLI：
@@ -184,7 +187,21 @@ ssh-release deploy
 
 `release` 模式发布成功后会输出版本号、版本目录和 `current` 软链接路径。只有压缩包上传和解压完成后才切换 `current`。
 
-如果远端已有 `.ssh-release.lock`，说明同一目标目录可能正在发布或回滚，工具会停止在修改远端状态之前。确认没有任务运行后，可以手动删除 `target.path/.ssh-release.lock` 再重试。
+如果远端已有 `.ssh-release.lock`，说明同一目标目录可能正在发布或回滚，工具会停止在修改远端状态之前。
+
+查看锁状态：
+
+```bash
+ssh-release unlock
+```
+
+确认没有发布或回滚任务运行后，可以显式确认锁路径并删除锁：
+
+```bash
+ssh-release unlock --confirm /var/www/my-app/.ssh-release.lock
+```
+
+`--confirm` 后的路径必须和当前配置计算出的锁路径完全一致，否则不会删除锁。
 
 远端 `tar` 不可用或解压失败时，如果 `deploy.fallbackToFileUpload` 为 `true`，工具会回退逐文件上传。`release` 模式只清理失败的新版本目录；`overwrite` 模式不会先删除整个目标目录。
 
@@ -208,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、密码或生产路径。
@@ -314,6 +357,7 @@ src/
 ├── rollback.ts
 ├── ssh.ts
 ├── types.ts
+├── unlock.ts
 └── validate.ts
 
 tests/
@@ -328,6 +372,7 @@ tests/
 ├── release.test.ts
 ├── rollback.test.ts
 ├── ssh.test.ts
+├── unlock.test.ts
 └── validate.test.ts
 
 docs/
@@ -345,11 +390,13 @@ docs/
 - 危险远程路径拒绝。
 - 发布模式和压缩格式校验。
 - CLI 命令分发。
+- CLI JSON 输出。
 - 本地 `.tgz` 打包和排除项。
 - macOS AppleDouble 元数据排除。
 - `release` 和 `overwrite` 发布流程。
 - 发布和回滚锁获取、释放和锁冲突拦截。
 - `doctor` 远端锁状态检查和安全清理提示。
+- `unlock` 显式确认路径后删除远端锁。
 - 远端 `tar` 失败后的逐文件上传回退。
 - 远程版本列表读取和当前版本标记。
 - `doctor` 检查结果。

package/dist/cli.js

@@ -8,6 +8,7 @@ import { listReleases } from './list.js';
 import { createDeployPlan, deploy } from './release.js';
 import { rollback } from './rollback.js';
 import { createRemoteClient } from './ssh.js';
+import { unlock } from './unlock.js';
 export function isCliEntrypoint(moduleUrl, argvEntry) {
     if (!argvEntry) {
         return false;
@@ -18,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);
@@ -35,39 +49,87 @@ 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 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;
     }
 }
 function parseCliArgs(argv) {
     const args = [];
+    let confirmPath;
     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];
@@ -79,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;
@@ -92,27 +158,39 @@ function parseCliArgs(argv) {
             dryRun = true;
             continue;
         }
+        if (arg === '--confirm') {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('-')) {
+                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);
     }
     return {
         args: args.slice(1),
         command: args[0],
+        confirmPath,
         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,
     };
 }
@@ -137,6 +215,10 @@ function createDefaultHandlers(configPath) {
         doctor: async () => {
             return runDoctorFromFile(configPath, createRemoteClient);
         },
+        unlock: async (options) => {
+            const config = await loadConfigFile(configPath);
+            return unlock(config, createRemoteClient(config), options);
+        },
     };
 }
 function printDeployResult(result, io) {
@@ -193,6 +275,36 @@ function printDoctorReport(report, io) {
         io.log(`[${check.status}] ${check.name}: ${check.message}`);
     }
 }
+function printUnlockResult(result, io) {
+    if (!result.locked) {
+        io.log(`没有发现远端锁: ${result.lockPath}`);
+        return;
+    }
+    if (result.removed) {
+        io.log(`已删除远端锁: ${result.lockPath}`);
+        return;
+    }
+    io.log(`发现远端锁: ${result.lockPath}`);
+    io.log(`pid: ${result.pid ?? '未知'}`);
+    io.log(`创建时间: ${result.createdAt ?? '未知'}`);
+    io.log('不会自动删除远端锁');
+    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);
@@ -202,20 +314,28 @@ 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 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/lock.js

@@ -38,6 +38,9 @@ export async function acquireRemoteLock(config, client, options = {}) {
         await client.exec(`rm -rf ${shellQuote(lockPath)}`);
     };
 }
+export async function removeRemoteLock(config, client) {
+    await client.exec(`rm -rf ${shellQuote(getRemoteLockPath(config))}`);
+}
 function parseRemoteLockValue(lines, fieldName) {
     const prefix = `${fieldName}=`;
     const line = lines.find((entry) => entry.startsWith(prefix));

package/dist/unlock.js

@@ -0,0 +1,24 @@
+import { readRemoteLockStatus, removeRemoteLock, } from './lock.js';
+export async function unlock(config, client, options = {}) {
+    const lockStatus = await readRemoteLockStatus(config, client);
+    if (!lockStatus.locked) {
+        return {
+            ...lockStatus,
+            removed: false,
+        };
+    }
+    if (!options.confirmPath) {
+        return {
+            ...lockStatus,
+            removed: false,
+        };
+    }
+    if (options.confirmPath !== lockStatus.lockPath) {
+        throw new Error(`确认路径不匹配: 需要 ${lockStatus.lockPath}`);
+    }
+    await removeRemoteLock(config, client);
+    return {
+        ...lockStatus,
+        removed: true,
+    };
+}

package/package.json

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