ssh-release 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.0 - 2026-06-25
+
+### Added
+
+- 增加 `ssh-release doctor` 远端锁状态检查，无锁时通过，有锁时提示锁路径、pid、创建时间和安全清理条件。
+
+## 0.2.0 - 2026-06-25
+
+### Added
+
+- 增加 `--help` 和 `--version`，方便安装后确认 CLI 能力和版本。
+- 增加 `--config <path>`，支持使用非默认配置文件。
+- 增加 `ssh-release deploy --dry-run`，可在不连接远端、不修改服务器的情况下查看发布计划。
+- 增加远端锁 `.ssh-release.lock`，避免同一目标目录并发发布或回滚。
+- 增加 GitHub Actions CI，在 `main` 推送和 Pull Request 上运行安装、类型检查、测试和构建。
+
 ## 0.1.0 - 2026-06-25
 
 首个 npm 版本。

package/README.md

@@ -11,7 +11,7 @@
 已实现：
 
 - `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]`：回滚到上一个版本或指定版本。
@@ -40,6 +40,13 @@ npm install -g ssh-release
 ssh-release init
 ```
 
+查看帮助和版本：
+
+```bash
+ssh-release --help
+ssh-release --version
+```
+
 ## 本地开发
 
 ```bash
@@ -78,6 +85,14 @@ npm run dev -- init
 
 生成的配置文件名为 `ssh-release.config.ts`。
 
+需要使用自定义配置路径时，可以传入 `--config`：
+
+```bash
+ssh-release init --config deploy.config.ts
+ssh-release doctor --config deploy.config.ts
+ssh-release deploy --config deploy.config.ts
+```
+
 配置文件应使用 `export default` 导出配置对象。当前模板支持从环境变量读取服务器地址和用户名：
 
 示例配置：
@@ -130,11 +145,14 @@ source files -> package -> upload -> release -> activate -> rollback
 ├── releases/
 │   ├── 20260625-153000/
 │   └── 20260625-150000/
+├── .ssh-release.lock/
 └── .ssh-release-tmp/
 ```
 
 规则：
 
+- 发布和回滚开始前会创建 `.ssh-release.lock`，避免同一目标目录并发修改。
+- 发布或回滚结束后会自动删除 `.ssh-release.lock`。
 - 每次发布创建一个新版本目录。
 - 新版本完整上传和解压完成后，才切换 `current`。
 - 回滚只切换 `current`，不删除版本目录。
@@ -150,6 +168,14 @@ source files -> package -> upload -> release -> activate -> rollback
 ssh-release doctor
 ```
 
+`doctor` 会检查 `.ssh-release.lock`。没有锁时正常通过；如果发现锁，会以 `warn` 显示锁路径、pid、创建时间和安全清理提示。
+
+需要先查看发布计划但不修改服务器时：
+
+```bash
+ssh-release deploy --dry-run
+```
+
 执行发布：
 
 ```bash
@@ -158,6 +184,8 @@ ssh-release deploy
 
 `release` 模式发布成功后会输出版本号、版本目录和 `current` 软链接路径。只有压缩包上传和解压完成后才切换 `current`。
 
+如果远端已有 `.ssh-release.lock`，说明同一目标目录可能正在发布或回滚，工具会停止在修改远端状态之前。确认没有任务运行后，可以手动删除 `target.path/.ssh-release.lock` 再重试。
+
 远端 `tar` 不可用或解压失败时，如果 `deploy.fallbackToFileUpload` 为 `true`，工具会回退逐文件上传。`release` 模式只清理失败的新版本目录；`overwrite` 模式不会先删除整个目标目录。
 
 查看版本：
@@ -239,6 +267,7 @@ npm run build
 - `npm run lint`：运行 TypeScript 静态检查。
 - `npm test`：运行 Node.js 测试。
 - `npm run build`：编译 `dist/`。
+- GitHub Actions 会在 `main` 推送和 Pull Request 上运行 `npm ci`、`lint`、`test` 和 `build`。
 
 ## 发布前检查
 
@@ -270,10 +299,13 @@ npm install -g "$PACK_DIR"/ssh-release-"$VERSION".tgz --prefix "$PACK_DIR/prefix
 
 ```text
 CHANGELOG.md
+.github/
+└── workflows/ci.yml
 src/
 ├── cli.ts
 ├── config.ts
 ├── doctor.ts
+├── lock.ts
 ├── list.ts
 ├── package.ts
 ├── process.ts
@@ -316,6 +348,8 @@ docs/
 - 本地 `.tgz` 打包和排除项。
 - macOS AppleDouble 元数据排除。
 - `release` 和 `overwrite` 发布流程。
+- 发布和回滚锁获取、释放和锁冲突拦截。
+- `doctor` 远端锁状态检查和安全清理提示。
 - 远端 `tar` 失败后的逐文件上传回退。
 - 远程版本列表读取和当前版本标记。
 - `doctor` 检查结果。

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { realpathSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 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 { deploy } from './release.js';
+import { createDeployPlan, deploy } from './release.js';
 import { rollback } from './rollback.js';
 import { createRemoteClient } from './ssh.js';
 export function isCliEntrypoint(moduleUrl, argvEntry) {
@@ -16,16 +16,30 @@ export function isCliEntrypoint(moduleUrl, argvEntry) {
 }
 export async function runCli(argv = process.argv.slice(2), options = {}) {
     const io = options.io ?? console;
-    const handlers = options.handlers ?? createDefaultHandlers();
-    const [command, ...args] = argv;
+    const parsed = parseCliArgs(argv);
+    if (parsed.error) {
+        io.error(parsed.error);
+        return 1;
+    }
+    if (parsed.help) {
+        printUsage(io);
+        return 0;
+    }
+    if (parsed.version) {
+        io.log(readPackageVersion());
+        return 0;
+    }
+    const handlers = options.handlers ?? createDefaultHandlers(parsed.configPath);
+    const command = parsed.command;
+    const args = parsed.args;
     try {
         if (command === 'init') {
             await handlers.init();
-            io.log('已创建 ssh-release.config.ts');
+            io.log(`已创建 ${parsed.configPath}`);
             return 0;
         }
         if (command === 'deploy') {
-            printDeployResult(await handlers.deploy(), io);
+            printDeployResult(await handlers.deploy({ dryRun: parsed.dryRun }), io);
             return 0;
         }
         if (command === 'rollback') {
@@ -41,12 +55,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             printDoctorReport(report, io);
             return report.ok ? 0 : 1;
         }
-        io.log(`用法:
-  ssh-release init
-  ssh-release deploy
-  ssh-release rollback [version]
-  ssh-release list
-  ssh-release doctor`);
+        printUsage(io);
         return command ? 1 : 0;
     }
     catch (error) {
@@ -54,27 +63,96 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         return 1;
     }
 }
-function createDefaultHandlers() {
+function parseCliArgs(argv) {
+    const args = [];
+    let configPath = CONFIG_FILE_NAME;
+    let dryRun = false;
+    let help = false;
+    let version = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+            continue;
+        }
+        if (arg === '--version' || arg === '-v') {
+            version = true;
+            continue;
+        }
+        if (arg === '--config' || arg === '-c') {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('-')) {
+                return createParsedError('--config 需要配置文件路径', configPath);
+            }
+            configPath = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--dry-run') {
+            dryRun = true;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            return createParsedError(`未知选项: ${arg}`, configPath);
+        }
+        args.push(arg);
+    }
+    return {
+        args: args.slice(1),
+        command: args[0],
+        configPath,
+        dryRun,
+        help,
+        version,
+    };
+}
+function createParsedError(error, configPath) {
     return {
-        init: () => writeConfigTemplate(),
-        deploy: async () => {
-            const config = await loadConfigFile();
+        args: [],
+        configPath,
+        dryRun: false,
+        error,
+        help: false,
+        version: false,
+    };
+}
+function createDefaultHandlers(configPath) {
+    return {
+        init: () => writeConfigTemplate(configPath),
+        deploy: async (options) => {
+            const config = await loadConfigFile(configPath);
+            if (options?.dryRun) {
+                return createDeployPlan(config);
+            }
             return deploy(config, createRemoteClient(config));
         },
         rollback: async (version) => {
-            const config = await loadConfigFile();
+            const config = await loadConfigFile(configPath);
             return rollback(config, createRemoteClient(config), version);
         },
         list: async () => {
-            const config = await loadConfigFile();
+            const config = await loadConfigFile(configPath);
             return listReleases(config, createRemoteClient(config));
         },
         doctor: async () => {
-            return runDoctorFromFile(CONFIG_FILE_NAME, createRemoteClient);
+            return runDoctorFromFile(configPath, createRemoteClient);
         },
     };
 }
 function printDeployResult(result, io) {
+    if ('dryRun' in result) {
+        io.log('发布预检通过，不会修改远程服务器');
+        io.log(`模式: ${result.mode}`);
+        io.log(`源路径: ${result.sourcePath}`);
+        io.log(`目标目录: ${result.targetPath}`);
+        if (result.version) {
+            io.log(`计划版本: ${result.version}`);
+        }
+        if (result.currentSymlink) {
+            io.log(`计划切换: ${result.currentSymlink}`);
+        }
+        return;
+    }
     if (result.mode === 'release') {
         io.log(`发布成功: ${result.version}`);
         io.log(`版本目录: ${result.targetPath}`);
@@ -94,6 +172,9 @@ function printDeployResult(result, io) {
 function printRollbackResult(result, io) {
     io.log(`已回滚到版本: ${result.version}`);
     io.log(`当前指向: ${result.currentSymlink}`);
+    for (const warning of result.warnings) {
+        io.log(`警告: ${warning}`);
+    }
 }
 function printListResult(result, io) {
     io.log(`远程目录: ${result.targetPath}`);
@@ -120,6 +201,21 @@ function toRealPath(filePath) {
         return resolve(filePath);
     }
 }
+function printUsage(io) {
+    io.log(`用法:
+  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 --help
+  ssh-release --version`);
+}
+function readPackageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return packageJson.version ?? '0.0.0';
+}
 if (isCliEntrypoint(import.meta.url, process.argv[1])) {
     const exitCode = await runCli();
     process.exit(exitCode);

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

@@ -0,0 +1,46 @@
+import { remoteJoin, shellQuote } from './remote.js';
+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);
+    const createdAtPath = remoteJoin(lockPath, 'created_at');
+    const pidPath = remoteJoin(lockPath, 'pid');
+    const lockedMessage = `远程已有发布任务正在运行，请确认后删除 ${lockPath}`;
+    const missingTargetMessage = `远程目标目录不存在: ${config.target.path}`;
+    const prepareTarget = createTargetPath
+        ? `mkdir -p ${shellQuote(config.target.path)}`
+        : `if [ -d ${shellQuote(config.target.path)} ]; then :; else echo ${shellQuote(missingTargetMessage)} >&2; exit 74; fi`;
+    const command = `${prepareTarget} && if mkdir ${shellQuote(lockPath)} 2>/dev/null; then printf '%s\\n' "$$" > ${shellQuote(pidPath)}; date -u '+%Y-%m-%dT%H:%M:%SZ' > ${shellQuote(createdAtPath)}; else echo ${shellQuote(lockedMessage)} >&2; exit 73; fi`;
+    await client.exec(command);
+    return async () => {
+        await client.exec(`rm -rf ${shellQuote(lockPath)}`);
+    };
+}
+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/release.js

@@ -1,5 +1,6 @@
 import { access } from 'node:fs/promises';
 import { createReleasePackage, } from './package.js';
+import { acquireRemoteLock } from './lock.js';
 import { readRemoteReleaseNames, remoteJoin, shellQuote, } from './remote.js';
 export function createVersionName(date = new Date()) {
     return [
@@ -30,21 +31,75 @@ export async function deploy(config, client, options = {}) {
     await ensureSourceExists(config.source.path);
     const versionName = createVersionName(options.now ?? new Date());
     const packageFactory = options.createPackage ?? createReleasePackage;
-    const releasePackage = await packageFactory({
-        sourcePath: config.source.path,
-        exclude: config.source.exclude,
-        versionName,
-    });
+    const releaseLock = await acquireRemoteLock(config, client);
+    let releasePackage;
+    let result;
+    let deployError;
+    let cleanupError;
     try {
+        releasePackage = await packageFactory({
+            sourcePath: config.source.path,
+            exclude: config.source.exclude,
+            versionName,
+        });
         if (config.deploy.mode === 'overwrite') {
-            return await deployOverwrite(config, client, releasePackage, versionName);
+            result = await deployOverwrite(config, client, releasePackage, versionName);
+            return result;
         }
-        return await deployRelease(config, client, releasePackage, versionName);
+        result = await deployRelease(config, client, releasePackage, versionName);
+        return result;
+    }
+    catch (error) {
+        deployError = error;
+        throw error;
     }
     finally {
-        await releasePackage.cleanup();
+        if (releasePackage) {
+            try {
+                await releasePackage.cleanup();
+            }
+            catch (error) {
+                cleanupError = error;
+            }
+        }
+        try {
+            await releaseLock();
+        }
+        catch (error) {
+            const message = `远程发布锁清理失败: ${formatError(error)}`;
+            if (result) {
+                result.warnings.push(message);
+            }
+            else if (!deployError && !cleanupError) {
+                cleanupError = error;
+            }
+        }
+        if (cleanupError && !deployError) {
+            throw cleanupError;
+        }
     }
 }
+export async function createDeployPlan(config, options = {}) {
+    await ensureSourceExists(config.source.path);
+    if (config.deploy.mode === 'overwrite') {
+        return {
+            dryRun: true,
+            mode: 'overwrite',
+            sourcePath: config.source.path,
+            targetPath: config.target.path,
+        };
+    }
+    const versionName = createVersionName(options.now ?? new Date());
+    const releasesPath = remoteJoin(config.target.path, config.target.releasesDir);
+    return {
+        dryRun: true,
+        mode: 'release',
+        version: versionName,
+        sourcePath: config.source.path,
+        targetPath: remoteJoin(releasesPath, versionName),
+        currentSymlink: remoteJoin(config.target.path, config.target.currentSymlink),
+    };
+}
 async function deployRelease(config, client, releasePackage, versionName) {
     const warnings = [];
     const releasesPath = remoteJoin(config.target.path, config.target.releasesDir);

package/dist/rollback.js

@@ -1,4 +1,5 @@
 import { readCurrentVersion, readRemoteReleaseNames, remoteJoin, shellQuote, } from './remote.js';
+import { acquireRemoteLock } from './lock.js';
 export function selectRollbackTarget(selection) {
     const releases = [...new Set(selection.releases)].sort();
     if (selection.requestedVersion) {
@@ -20,21 +21,49 @@ export async function rollback(config, client, requestedVersion) {
     if (config.deploy.mode === 'overwrite') {
         throw new Error('overwrite 模式不支持回滚');
     }
-    const releasesPath = remoteJoin(config.target.path, config.target.releasesDir);
-    const currentSymlinkPath = remoteJoin(config.target.path, config.target.currentSymlink);
-    const releases = await readRemoteReleaseNames(client, releasesPath);
-    const currentVersion = await readCurrentVersion(client, currentSymlinkPath);
-    if (!currentVersion) {
-        throw new Error('当前版本不存在');
+    const releaseLock = await acquireRemoteLock(config, client, { createTargetPath: false });
+    let result;
+    let rollbackError;
+    try {
+        const releasesPath = remoteJoin(config.target.path, config.target.releasesDir);
+        const currentSymlinkPath = remoteJoin(config.target.path, config.target.currentSymlink);
+        const releases = await readRemoteReleaseNames(client, releasesPath);
+        const currentVersion = await readCurrentVersion(client, currentSymlinkPath);
+        if (!currentVersion) {
+            throw new Error('当前版本不存在');
+        }
+        const targetVersion = selectRollbackTarget({
+            releases,
+            currentVersion,
+            requestedVersion,
+        });
+        await client.exec(`ln -sfn ${shellQuote(remoteJoin(config.target.releasesDir, targetVersion))} ${shellQuote(currentSymlinkPath)}`);
+        result = {
+            version: targetVersion,
+            currentSymlink: currentSymlinkPath,
+            warnings: [],
+        };
+        return result;
+    }
+    catch (error) {
+        rollbackError = error;
+        throw error;
+    }
+    finally {
+        try {
+            await releaseLock();
+        }
+        catch (error) {
+            const message = `远程发布锁清理失败: ${formatError(error)}`;
+            if (result) {
+                result.warnings.push(message);
+            }
+            else if (!rollbackError) {
+                throw error;
+            }
+        }
     }
-    const targetVersion = selectRollbackTarget({
-        releases,
-        currentVersion,
-        requestedVersion,
-    });
-    await client.exec(`ln -sfn ${shellQuote(remoteJoin(config.target.releasesDir, targetVersion))} ${shellQuote(currentSymlinkPath)}`);
-    return {
-        version: targetVersion,
-        currentSymlink: currentSymlinkPath,
-    };
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
 }

package/package.json

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