ssh-release 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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,7 @@
 - `ssh-release deploy`：发布本地文件或目录。
 - `ssh-release list`：查看远程版本和当前版本。
 - `ssh-release rollback [version]`：回滚到上一个版本或指定版本。
+- `ssh-release unlock`：查看远端锁，并在显式确认锁路径后删除锁。
 - `release` 模式：上传压缩包、远端解压、切换 `current`、清理旧版本。
 - `overwrite` 模式：直接覆盖发布到目标目录。
 - 远端 `tar` 解压失败时回退逐文件上传。
@@ -55,6 +56,7 @@ npm run dev -- doctor
 npm run dev -- deploy
 npm run dev -- list
 npm run dev -- rollback
+npm run dev -- unlock
 ```
 
 构建 CLI：
@@ -184,7 +186,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` 模式不会先删除整个目标目录。
 
@@ -314,6 +330,7 @@ src/
 ├── rollback.ts
 ├── ssh.ts
 ├── types.ts
+├── unlock.ts
 └── validate.ts
 
 tests/
@@ -328,6 +345,7 @@ tests/
 ├── release.test.ts
 ├── rollback.test.ts
 ├── ssh.test.ts
+├── unlock.test.ts
 └── validate.test.ts
 
 docs/
@@ -350,6 +368,7 @@ docs/
 - `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;
@@ -55,6 +56,11 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             printDoctorReport(report, io);
             return report.ok ? 0 : 1;
         }
+        if (command === 'unlock') {
+            const result = await handlers.unlock({ confirmPath: parsed.confirmPath });
+            printUnlockResult(result, io);
+            return result.locked && !result.removed ? 1 : 0;
+        }
         printUsage(io);
         return command ? 1 : 0;
     }
@@ -65,6 +71,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
 }
 function parseCliArgs(argv) {
     const args = [];
+    let confirmPath;
     let configPath = CONFIG_FILE_NAME;
     let dryRun = false;
     let help = false;
@@ -92,6 +99,15 @@ function parseCliArgs(argv) {
             dryRun = true;
             continue;
         }
+        if (arg === '--confirm') {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('-')) {
+                return createParsedError('--confirm 需要远端锁路径', configPath);
+            }
+            confirmPath = value;
+            index += 1;
+            continue;
+        }
         if (arg.startsWith('-')) {
             return createParsedError(`未知选项: ${arg}`, configPath);
         }
@@ -100,6 +116,7 @@ function parseCliArgs(argv) {
     return {
         args: args.slice(1),
         command: args[0],
+        confirmPath,
         configPath,
         dryRun,
         help,
@@ -137,6 +154,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 +214,22 @@ 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 toRealPath(filePath) {
     try {
         return realpathSync(filePath);
@@ -209,6 +246,7 @@ function printUsage(io) {
   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 --help
   ssh-release --version`);
 }

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