ssh-release 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.0 - 2026-06-25
+
+### Added
+
+- 增加 `ssh-release unlock` 安全解锁流程，默认只查看远端锁，必须传入匹配的 `--confirm <lock-path>` 才会删除锁目录。
+
+## 0.3.0 - 2026-06-25
+
+### Added
+
+- 增加 `ssh-release doctor` 远端锁状态检查，无锁时通过，有锁时提示锁路径、pid、创建时间和安全清理条件。
+
 ## 0.2.0 - 2026-06-25
 
 ### Added

package/README.md

@@ -11,10 +11,11 @@
 已实现：
 
 - `ssh-release init`：生成 `ssh-release.config.ts` 配置模板。
-- `ssh-release doctor`：检查配置、本地源路径、SSH 连接、远程目录和远端 `tar`。
+- `ssh-release doctor`：检查配置、本地源路径、SSH 连接、远程目录、远端锁和远端 `tar`。
 - `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：
@@ -168,6 +170,8 @@ source files -> package -> upload -> release -> activate -> rollback
 ssh-release doctor
 ```
 
+`doctor` 会检查 `.ssh-release.lock`。没有锁时正常通过；如果发现锁，会以 `warn` 显示锁路径、pid、创建时间和安全清理提示。
+
 需要先查看发布计划但不修改服务器时：
 
 ```bash
@@ -182,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` 模式不会先删除整个目标目录。
 
@@ -312,6 +330,7 @@ src/
 ├── rollback.ts
 ├── ssh.ts
 ├── types.ts
+├── unlock.ts
 └── validate.ts
 
 tests/
@@ -326,6 +345,7 @@ tests/
 ├── release.test.ts
 ├── rollback.test.ts
 ├── ssh.test.ts
+├── unlock.test.ts
 └── validate.test.ts
 
 docs/
@@ -347,6 +367,8 @@ docs/
 - 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;
@@ -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/doctor.js

@@ -1,5 +1,6 @@
 import { access } from 'node:fs/promises';
 import { loadConfigFile } from './config.js';
+import { readRemoteLockStatus } from './lock.js';
 import { shellQuote } from './remote.js';
 export async function runDoctorFromFile(configPath, createClient) {
     let config;
@@ -33,6 +34,7 @@ export async function runDoctor(config, client, options = {}) {
     await addSourcePathCheck(checks, config.source.path);
     await addRemoteCheck(checks, 'SSH 连接', () => client.exec('true'), 'SSH 可连接');
     await addRemoteCheck(checks, '远程目录', () => client.exec(`mkdir -p ${shellQuote(config.target.path)} && test -w ${shellQuote(config.target.path)}`), '远程目录可创建且可写');
+    await addRemoteLockCheck(checks, config, client);
     try {
         await client.exec('command -v tar');
         checks.push({
@@ -78,6 +80,36 @@ async function addConfigFileCheck(checks, configPath) {
         });
     }
 }
+async function addRemoteLockCheck(checks, config, client) {
+    try {
+        const lockStatus = await readRemoteLockStatus(config, client);
+        if (!lockStatus.locked) {
+            checks.push({
+                name: '远端锁',
+                status: 'pass',
+                message: '没有发现发布或回滚锁',
+            });
+            return;
+        }
+        checks.push({
+            name: '远端锁',
+            status: 'warn',
+            message: [
+                `发现远端锁: ${lockStatus.lockPath}`,
+                `pid: ${lockStatus.pid ?? '未知'}`,
+                `创建时间: ${lockStatus.createdAt ?? '未知'}`,
+                '确认没有发布或回滚任务后再手动删除该目录',
+            ].join('；'),
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: '远端锁',
+            status: 'fail',
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 async function addSourcePathCheck(checks, sourcePath) {
     try {
         await access(sourcePath);

package/dist/lock.js

@@ -3,6 +3,25 @@ const remoteLockDir = '.ssh-release.lock';
 export function getRemoteLockPath(config) {
     return remoteJoin(config.target.path, remoteLockDir);
 }
+export async function readRemoteLockStatus(config, client) {
+    const lockPath = getRemoteLockPath(config);
+    const pidPath = remoteJoin(lockPath, 'pid');
+    const createdAtPath = remoteJoin(lockPath, 'created_at');
+    const result = await client.exec(`if [ -d ${shellQuote(lockPath)} ]; then echo locked; printf 'pid='; cat ${shellQuote(pidPath)} 2>/dev/null || true; printf '\\ncreated_at='; cat ${shellQuote(createdAtPath)} 2>/dev/null || true; printf '\\n'; else echo unlocked; fi`);
+    const lines = result.stdout.split('\n').map((line) => line.trim());
+    if (lines[0] !== 'locked') {
+        return {
+            locked: false,
+            lockPath,
+        };
+    }
+    return {
+        locked: true,
+        lockPath,
+        pid: parseRemoteLockValue(lines, 'pid'),
+        createdAt: parseRemoteLockValue(lines, 'created_at'),
+    };
+}
 export async function acquireRemoteLock(config, client, options = {}) {
     const createTargetPath = options.createTargetPath ?? true;
     const lockPath = getRemoteLockPath(config);
@@ -19,3 +38,12 @@ 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));
+    const value = line?.slice(prefix.length).trim();
+    return value || undefined;
+}

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