ssh-release 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 - 2026-06-25
+
+首个 npm 版本。
+
+### Added
+
+- 提供 `ssh-release init` 生成配置模板。
+- 提供 `ssh-release doctor` 检查配置、本地源路径、SSH 连接、远程目录和远端 `tar`。
+- 提供 `ssh-release deploy` 发布本地文件或目录。
+- 提供 `ssh-release list` 查看远程版本和当前版本。
+- 提供 `ssh-release rollback [version]` 回滚到上一个版本或指定版本。
+- 支持 `release` 模式：上传压缩包、远端解压、切换 `current`、清理旧版本。
+- 支持 `overwrite` 模式：直接覆盖发布到目标目录。
+- 支持远端 `tar` 失败后逐文件上传回退。
+- 支持私钥登录和密码登录；密码通过 `SSHPASS` 环境变量交给 `sshpass -e`。
+- 拦截危险远程目标路径和不安全的目标辅助目录名。
+- macOS 打包时排除 AppleDouble 和扩展属性元数据。
+
+### Verified
+
+- 通过单元测试和 fake `ssh`/`scp` 端到端测试覆盖核心发布、列表、回滚和覆盖发布流程。
+- 通过真实服务器验证密码登录、`doctor`、`deploy`、`list`、`rollback` 和 `overwrite` 流程。
+- 通过 `npm publish --dry-run` 和本地 tarball 安装烟测验证 npm 包内容和 CLI 入口。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,337 @@
+# ssh-release
+
+`ssh-release` 是一个通用 SSH 文件发布 CLI，目标是把本地文件或目录可靠发布到服务器。
+
+它只负责文件发布和版本切换，不负责构建项目、重启服务、修改 Nginx、操作容器或执行自定义远程脚本。
+
+## 当前状态
+
+当前仓库已完成第一版 MVP。
+
+已实现：
+
+- `ssh-release init`：生成 `ssh-release.config.ts` 配置模板。
+- `ssh-release doctor`：检查配置、本地源路径、SSH 连接、远程目录和远端 `tar`。
+- `ssh-release deploy`：发布本地文件或目录。
+- `ssh-release list`：查看远程版本和当前版本。
+- `ssh-release rollback [version]`：回滚到上一个版本或指定版本。
+- `release` 模式：上传压缩包、远端解压、切换 `current`、清理旧版本。
+- `overwrite` 模式：直接覆盖发布到目标目录。
+- 远端 `tar` 解压失败时回退逐文件上传。
+- 配置字段归一化、危险远程路径拦截、版本号生成、旧版本保留计算和回滚目标选择。
+
+## 安装依赖
+
+```bash
+npm install
+```
+
+## 全局安装
+
+发布到 npm 后，可以在任意项目中全局安装：
+
+```bash
+npm install -g ssh-release
+```
+
+安装后在需要发布文件的项目目录中执行：
+
+```bash
+ssh-release init
+```
+
+## 本地开发
+
+```bash
+npm run dev -- init
+npm run dev -- doctor
+npm run dev -- deploy
+npm run dev -- list
+npm run dev -- rollback
+```
+
+构建 CLI：
+
+```bash
+npm run build
+```
+
+构建后可以直接运行：
+
+```bash
+node dist/cli.js init
+```
+
+## 配置初始化
+
+在需要发布文件的项目目录中执行：
+
+```bash
+ssh-release init
+```
+
+当前开发阶段也可以用源码入口执行：
+
+```bash
+npm run dev -- init
+```
+
+生成的配置文件名为 `ssh-release.config.ts`。
+
+配置文件应使用 `export default` 导出配置对象。当前模板支持从环境变量读取服务器地址和用户名：
+
+示例配置：
+
+```ts
+export default {
+  source: {
+    path: './dist',
+    exclude: ['.DS_Store', 'node_modules'],
+  },
+
+  server: {
+    host: process.env.SSH_RELEASE_HOST,
+    port: 22,
+    username: process.env.SSH_RELEASE_USER,
+    password: process.env.SSH_RELEASE_PASSWORD,
+    privateKeyPath: '~/.ssh/id_rsa',
+  },
+
+  target: {
+    path: '/var/www/my-app',
+    currentSymlink: 'current',
+    releasesDir: 'releases',
+    tempDir: '.ssh-release-tmp',
+  },
+
+  deploy: {
+    mode: 'release',
+    keepReleases: 5,
+    compression: 'tgz',
+    preferTar: true,
+    fallbackToFileUpload: true,
+  },
+};
+```
+
+## 发布模型
+
+默认发布模型是版本化发布：
+
+```text
+source files -> package -> upload -> release -> activate -> rollback
+```
+
+`release` 模式下，远程目录规划如下：
+
+```text
+/var/www/my-app/
+├── current -> releases/20260625-153000
+├── releases/
+│   ├── 20260625-153000/
+│   └── 20260625-150000/
+└── .ssh-release-tmp/
+```
+
+规则：
+
+- 每次发布创建一个新版本目录。
+- 新版本完整上传和解压完成后，才切换 `current`。
+- 回滚只切换 `current`，不删除版本目录。
+- 清理旧版本时保留当前版本。
+
+`overwrite` 模式用于不需要版本管理的目录，会直接发布到 `target.path`，不创建 `current` 和 `releases`。
+
+## 发布命令
+
+发布前先检查配置和远端环境：
+
+```bash
+ssh-release doctor
+```
+
+执行发布：
+
+```bash
+ssh-release deploy
+```
+
+`release` 模式发布成功后会输出版本号、版本目录和 `current` 软链接路径。只有压缩包上传和解压完成后才切换 `current`。
+
+远端 `tar` 不可用或解压失败时，如果 `deploy.fallbackToFileUpload` 为 `true`，工具会回退逐文件上传。`release` 模式只清理失败的新版本目录；`overwrite` 模式不会先删除整个目标目录。
+
+查看版本：
+
+```bash
+ssh-release list
+```
+
+回滚到上一个版本：
+
+```bash
+ssh-release rollback
+```
+
+回滚到指定版本：
+
+```bash
+ssh-release rollback 20260625-150000
+```
+
+`overwrite` 模式没有版本列表，也不支持回滚。
+
+## 安全边界
+
+配置模板不包含真实 IP、密码或生产路径。
+
+推荐通过环境变量提供服务器信息：
+
+```bash
+export SSH_RELEASE_HOST=example.com
+export SSH_RELEASE_USER=deploy
+export SSH_RELEASE_PASSWORD='your-password'
+```
+
+认证方式支持私钥和密码：
+
+- 设置 `server.privateKeyPath` 时使用私钥登录。
+- 设置 `server.password` 时使用密码登录，推荐写成 `process.env.SSH_RELEASE_PASSWORD`。
+- 同时设置 `password` 和 `privateKeyPath` 时，优先使用密码登录。
+- 密码不会作为命令行参数传给 `ssh` 或 `scp`，运行时通过 `SSHPASS` 环境变量交给 `sshpass -e`。
+- 不要把真实密码写进 `ssh-release.config.ts` 或仓库文件。
+
+以下远程目标路径会被默认拒绝：
+
+- `/`
+- `/home`
+- `/root`
+- `/var`
+- `/usr`
+- `/etc`
+- `/opt`
+- `/tmp`
+
+这些路径下的子目录可以使用，例如 `/var/www/my-app`。
+
+`target.currentSymlink`、`target.releasesDir` 和 `target.tempDir` 必须是简单相对名称，不能包含 `/`、`\`，也不能等于 `.` 或 `..`。
+
+本地需要可用的系统命令：
+
+- `tar`：本地打包发布内容。
+- `ssh`：执行远端目录、解压、软链接、列表和检查命令。
+- `scp`：上传压缩包和逐文件回退上传。
+- `sshpass`：仅密码登录时需要；私钥登录不需要。
+
+在 macOS 上打包时会禁用 AppleDouble 和扩展属性元数据，避免把 `._*` 文件发布到 Linux 服务器。
+
+远端 `tar` 是可选能力，不可用时会按配置回退逐文件上传。
+
+## 开发命令
+
+```bash
+npm run lint
+npm test
+npm run build
+```
+
+命令说明：
+
+- `npm run lint`：运行 TypeScript 静态检查。
+- `npm test`：运行 Node.js 测试。
+- `npm run build`：编译 `dist/`。
+
+## 发布前检查
+
+发布前先运行完整校验：
+
+```bash
+npm run prepublishOnly
+npm publish --dry-run
+```
+
+需要验证 npm 安装后的真实命令入口时，可以使用本地 tarball 做烟测：
+
+```bash
+PACK_DIR=$(mktemp -d)
+VERSION=$(node -p "JSON.parse(require('fs').readFileSync('package.json', 'utf8')).version")
+npm pack --pack-destination "$PACK_DIR"
+npm install -g "$PACK_DIR"/ssh-release-"$VERSION".tgz --prefix "$PACK_DIR/prefix"
+"$PACK_DIR/prefix/bin/ssh-release"
+"$PACK_DIR/prefix/bin/ssh-release" init
+```
+
+`npm publish` 会发布到 npm registry，只有确认版本号、包内容、登录账号和发布权限都正确后再执行。
+
+完整发布步骤见 [docs/release-checklist.md](https://github.com/JackEngineer/ssh-release/blob/main/docs/release-checklist.md)。
+
+版本变更见 [CHANGELOG.md](https://github.com/JackEngineer/ssh-release/blob/main/CHANGELOG.md)。
+
+## 项目结构
+
+```text
+CHANGELOG.md
+src/
+├── cli.ts
+├── config.ts
+├── doctor.ts
+├── list.ts
+├── package.ts
+├── process.ts
+├── remote.ts
+├── release.ts
+├── rollback.ts
+├── ssh.ts
+├── types.ts
+└── validate.ts
+
+tests/
+├── cli.test.ts
+├── config-load.test.ts
+├── config-template.test.ts
+├── deploy.test.ts
+├── e2e.test.ts
+├── list-doctor.test.ts
+├── package-json.test.ts
+├── package.test.ts
+├── release.test.ts
+├── rollback.test.ts
+├── ssh.test.ts
+└── validate.test.ts
+
+docs/
+├── release-checklist.md
+└── superpowers/specs/2026-06-25-ssh-release-design.md
+```
+
+## 测试重点
+
+当前测试覆盖：
+
+- 配置模板不泄露真实主机、密码和 IP。
+- 配置文件加载和 `~` 路径展开。
+- 配置默认值填充。
+- 危险远程路径拒绝。
+- 发布模式和压缩格式校验。
+- CLI 命令分发。
+- 本地 `.tgz` 打包和排除项。
+- macOS AppleDouble 元数据排除。
+- `release` 和 `overwrite` 发布流程。
+- 远端 `tar` 失败后的逐文件上传回退。
+- 远程版本列表读取和当前版本标记。
+- `doctor` 检查结果。
+- 通过临时 fake `ssh`/`scp` 进程执行端到端发布、列表、回滚和覆盖发布验收。
+- 时间戳版本名生成。
+- 旧版本清理选择。
+- 回滚目标选择。
+
+## 设计文档
+
+完整设计见：
+
+```text
+docs/superpowers/specs/2026-06-25-ssh-release-design.md
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import { 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 { rollback } from './rollback.js';
+import { createRemoteClient } from './ssh.js';
+export function isCliEntrypoint(moduleUrl, argvEntry) {
+    if (!argvEntry) {
+        return false;
+    }
+    return toRealPath(fileURLToPath(moduleUrl)) === toRealPath(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;
+    try {
+        if (command === 'init') {
+            await handlers.init();
+            io.log('已创建 ssh-release.config.ts');
+            return 0;
+        }
+        if (command === 'deploy') {
+            printDeployResult(await handlers.deploy(), io);
+            return 0;
+        }
+        if (command === 'rollback') {
+            printRollbackResult(await handlers.rollback(args[0]), io);
+            return 0;
+        }
+        if (command === 'list') {
+            printListResult(await handlers.list(), io);
+            return 0;
+        }
+        if (command === 'doctor') {
+            const report = await handlers.doctor();
+            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`);
+        return command ? 1 : 0;
+    }
+    catch (error) {
+        io.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+function createDefaultHandlers() {
+    return {
+        init: () => writeConfigTemplate(),
+        deploy: async () => {
+            const config = await loadConfigFile();
+            return deploy(config, createRemoteClient(config));
+        },
+        rollback: async (version) => {
+            const config = await loadConfigFile();
+            return rollback(config, createRemoteClient(config), version);
+        },
+        list: async () => {
+            const config = await loadConfigFile();
+            return listReleases(config, createRemoteClient(config));
+        },
+        doctor: async () => {
+            return runDoctorFromFile(CONFIG_FILE_NAME, createRemoteClient);
+        },
+    };
+}
+function printDeployResult(result, io) {
+    if (result.mode === 'release') {
+        io.log(`发布成功: ${result.version}`);
+        io.log(`版本目录: ${result.targetPath}`);
+        io.log(`当前指向: ${result.currentSymlink}`);
+    }
+    else {
+        io.log('覆盖发布成功');
+        io.log(`目标目录: ${result.targetPath}`);
+    }
+    if (result.usedFallback) {
+        io.log('远端 tar 不可用或解压失败，已使用逐文件上传');
+    }
+    for (const warning of result.warnings) {
+        io.log(`警告: ${warning}`);
+    }
+}
+function printRollbackResult(result, io) {
+    io.log(`已回滚到版本: ${result.version}`);
+    io.log(`当前指向: ${result.currentSymlink}`);
+}
+function printListResult(result, io) {
+    io.log(`远程目录: ${result.targetPath}`);
+    if (result.mode === 'overwrite') {
+        io.log('overwrite 模式没有版本列表');
+        return;
+    }
+    io.log(`当前版本: ${result.currentVersion ?? '未设置'}`);
+    for (const release of result.releases) {
+        const marker = release.current ? '*' : ' ';
+        io.log(`${marker} ${release.version} ${release.modifiedAt.toISOString()}`);
+    }
+}
+function printDoctorReport(report, io) {
+    for (const check of report.checks) {
+        io.log(`[${check.status}] ${check.name}: ${check.message}`);
+    }
+}
+function toRealPath(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return resolve(filePath);
+    }
+}
+if (isCliEntrypoint(import.meta.url, process.argv[1])) {
+    const exitCode = await runCli();
+    process.exit(exitCode);
+}

package/dist/config.js

@@ -0,0 +1,77 @@
+import { pathToFileURL } from 'node:url';
+import { readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { normalizeConfig } from './validate.js';
+export const CONFIG_FILE_NAME = 'ssh-release.config.ts';
+export function createConfigTemplate() {
+    return `export default {
+  source: {
+    path: './dist',
+    exclude: ['.DS_Store', 'node_modules'],
+  },
+
+  server: {
+    host: process.env.SSH_RELEASE_HOST,
+    port: 22,
+    username: process.env.SSH_RELEASE_USER,
+    password: process.env.SSH_RELEASE_PASSWORD,
+    privateKeyPath: '~/.ssh/id_rsa',
+  },
+
+  target: {
+    path: '/var/www/my-app',
+    currentSymlink: 'current',
+    releasesDir: 'releases',
+    tempDir: '.ssh-release-tmp',
+  },
+
+  deploy: {
+    mode: 'release',
+    keepReleases: 5,
+    compression: 'tgz',
+    preferTar: true,
+    fallbackToFileUpload: true,
+  },
+};
+`;
+}
+export async function writeConfigTemplate(configPath = CONFIG_FILE_NAME) {
+    await writeFile(configPath, createConfigTemplate(), { flag: 'wx' });
+}
+export async function loadConfigFile(configPath = CONFIG_FILE_NAME) {
+    const absolutePath = path.resolve(configPath);
+    const input = await loadConfigInput(absolutePath);
+    const config = normalizeConfig(input);
+    return {
+        ...config,
+        server: {
+            ...config.server,
+            privateKeyPath: config.server.privateKeyPath
+                ? resolveUserPath(config.server.privateKeyPath)
+                : undefined,
+        },
+    };
+}
+export function resolveUserPath(filePath) {
+    if (filePath === '~') {
+        return os.homedir();
+    }
+    if (filePath.startsWith('~/')) {
+        return path.join(os.homedir(), filePath.slice(2));
+    }
+    return filePath;
+}
+async function loadConfigInput(configPath) {
+    if (configPath.endsWith('.js') || configPath.endsWith('.mjs')) {
+        const module = await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`);
+        return module.default;
+    }
+    const content = await readFile(configPath, 'utf8');
+    const transformed = content.replace(/^\s*export\s+default\s+/, 'return ');
+    if (transformed === content) {
+        throw new Error('配置文件必须使用 export default 导出配置对象');
+    }
+    const factory = new Function('process', transformed);
+    return factory(process);
+}

package/dist/doctor.js

@@ -0,0 +1,114 @@
+import { access } from 'node:fs/promises';
+import { loadConfigFile } from './config.js';
+import { shellQuote } from './remote.js';
+export async function runDoctorFromFile(configPath, createClient) {
+    let config;
+    try {
+        config = await loadConfigFile(configPath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const isMissing = message.includes('ENOENT');
+        return {
+            ok: false,
+            checks: [
+                {
+                    name: isMissing ? '配置文件' : '配置字段',
+                    status: 'fail',
+                    message: isMissing ? `配置文件不存在: ${configPath}` : message,
+                },
+            ],
+        };
+    }
+    return runDoctor(config, createClient(config), { configPath });
+}
+export async function runDoctor(config, client, options = {}) {
+    const checks = [];
+    await addConfigFileCheck(checks, options.configPath);
+    checks.push({
+        name: '配置字段',
+        status: 'pass',
+        message: '配置字段有效',
+    });
+    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)}`), '远程目录可创建且可写');
+    try {
+        await client.exec('command -v tar');
+        checks.push({
+            name: '远端 tar',
+            status: 'pass',
+            message: '远端 tar 可用',
+        });
+    }
+    catch {
+        checks.push({
+            name: '远端 tar',
+            status: 'warn',
+            message: '远端 tar 不可用，将回退逐文件上传',
+        });
+    }
+    return {
+        ok: checks.every((check) => check.status !== 'fail'),
+        checks,
+    };
+}
+async function addConfigFileCheck(checks, configPath) {
+    if (!configPath) {
+        checks.push({
+            name: '配置文件',
+            status: 'pass',
+            message: '配置文件已加载',
+        });
+        return;
+    }
+    try {
+        await access(configPath);
+        checks.push({
+            name: '配置文件',
+            status: 'pass',
+            message: `配置文件存在: ${configPath}`,
+        });
+    }
+    catch {
+        checks.push({
+            name: '配置文件',
+            status: 'fail',
+            message: `配置文件不存在: ${configPath}`,
+        });
+    }
+}
+async function addSourcePathCheck(checks, sourcePath) {
+    try {
+        await access(sourcePath);
+        checks.push({
+            name: '本地源路径',
+            status: 'pass',
+            message: `本地源路径存在: ${sourcePath}`,
+        });
+    }
+    catch {
+        checks.push({
+            name: '本地源路径',
+            status: 'fail',
+            message: `本地源路径不存在: ${sourcePath}`,
+        });
+    }
+}
+async function addRemoteCheck(checks, name, run, successMessage) {
+    try {
+        await run();
+        checks.push({
+            name,
+            status: 'pass',
+            message: successMessage,
+        });
+    }
+    catch (error) {
+        checks.push({
+            name,
+            status: 'fail',
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+}

package/dist/list.js

@@ -0,0 +1,25 @@
+import { readCurrentVersion, readRemoteReleaseEntries, remoteJoin, } from './remote.js';
+export async function listReleases(config, client) {
+    if (config.deploy.mode === 'overwrite') {
+        return {
+            mode: 'overwrite',
+            targetPath: config.target.path,
+            releases: [],
+        };
+    }
+    const releasesPath = remoteJoin(config.target.path, config.target.releasesDir);
+    const currentSymlinkPath = remoteJoin(config.target.path, config.target.currentSymlink);
+    const [currentVersion, releases] = await Promise.all([
+        readCurrentVersion(client, currentSymlinkPath),
+        readRemoteReleaseEntries(client, releasesPath),
+    ]);
+    return {
+        mode: 'release',
+        targetPath: config.target.path,
+        currentVersion,
+        releases: releases.map((release) => ({
+            ...release,
+            current: release.version === currentVersion,
+        })),
+    };
+}

package/dist/package.js

@@ -0,0 +1,53 @@
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { runProcess } from './process.js';
+export async function createReleasePackage(options) {
+    const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'ssh-release-'));
+    const archivePath = path.join(tempDirectory, `${options.versionName}.tgz`);
+    const sourceStat = await stat(options.sourcePath);
+    const excludeArgs = options.exclude.flatMap((pattern) => ['--exclude', pattern]);
+    if (sourceStat.isDirectory()) {
+        await runProcess('tar', [
+            '-czf',
+            archivePath,
+            '--no-xattrs',
+            ...excludeArgs,
+            '-C',
+            options.sourcePath,
+            '.',
+        ], {
+            env: {
+                COPYFILE_DISABLE: '1',
+            },
+        });
+    }
+    else {
+        await runProcess('tar', [
+            '-czf',
+            archivePath,
+            '--no-xattrs',
+            ...excludeArgs,
+            '-C',
+            path.dirname(options.sourcePath),
+            path.basename(options.sourcePath),
+        ], {
+            env: {
+                COPYFILE_DISABLE: '1',
+            },
+        });
+    }
+    return {
+        archivePath,
+        cleanup: async () => {
+            await rm(tempDirectory, { recursive: true, force: true });
+        },
+    };
+}
+export async function listPackageEntries(archivePath) {
+    const result = await runProcess('tar', ['-tzf', archivePath]);
+    return result.stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+}

package/dist/process.js

@@ -0,0 +1,29 @@
+import { spawn } from 'node:child_process';
+export async function runProcess(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: {
+                ...process.env,
+                ...options.env,
+            },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        child.on('error', reject);
+        child.on('close', (code) => {
+            const result = {
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+            };
+            if (code === 0 || options.allowFailure) {
+                resolve(result);
+                return;
+            }
+            reject(new Error(`${command} 执行失败: ${result.stderr.trim() || `exit ${code}`}`));
+        });
+    });
+}

package/dist/release.js

@@ -0,0 +1,138 @@
+import { access } from 'node:fs/promises';
+import { createReleasePackage, } from './package.js';
+import { readRemoteReleaseNames, remoteJoin, shellQuote, } from './remote.js';
+export function createVersionName(date = new Date()) {
+    return [
+        date.getFullYear().toString(),
+        pad(date.getMonth() + 1),
+        pad(date.getDate()),
+        '-',
+        pad(date.getHours()),
+        pad(date.getMinutes()),
+        pad(date.getSeconds()),
+    ].join('');
+}
+export function selectReleasesToDelete(releases, currentVersion, keepReleases) {
+    if (!Number.isInteger(keepReleases) || keepReleases < 1) {
+        throw new Error('keepReleases 必须是正整数');
+    }
+    const sortedReleases = [...new Set(releases)].sort();
+    const retained = new Set(sortedReleases.slice(-keepReleases));
+    if (currentVersion) {
+        retained.add(currentVersion);
+    }
+    return sortedReleases.filter((release) => !retained.has(release));
+}
+function pad(value) {
+    return value.toString().padStart(2, '0');
+}
+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,
+    });
+    try {
+        if (config.deploy.mode === 'overwrite') {
+            return await deployOverwrite(config, client, releasePackage, versionName);
+        }
+        return await deployRelease(config, client, releasePackage, versionName);
+    }
+    finally {
+        await releasePackage.cleanup();
+    }
+}
+async function deployRelease(config, client, releasePackage, versionName) {
+    const warnings = [];
+    const releasesPath = remoteJoin(config.target.path, config.target.releasesDir);
+    const releasePath = remoteJoin(releasesPath, versionName);
+    const tempPath = remoteJoin(config.target.path, config.target.tempDir);
+    const remoteArchivePath = remoteJoin(tempPath, `${versionName}.tgz`);
+    const currentSymlinkPath = remoteJoin(config.target.path, config.target.currentSymlink);
+    await client.exec(`mkdir -p ${shellQuote(releasesPath)} ${shellQuote(tempPath)} ${shellQuote(releasePath)}`);
+    await client.uploadFile(releasePackage.archivePath, remoteArchivePath);
+    const usedFallback = await publishPackageToRemotePath(config, client, remoteArchivePath, releasePath, true);
+    await client.exec(`ln -sfn ${shellQuote(remoteJoin(config.target.releasesDir, versionName))} ${shellQuote(currentSymlinkPath)}`);
+    await cleanupRemoteArchive(client, remoteArchivePath, warnings);
+    await cleanupOldReleases(config, client, releasesPath, versionName, warnings);
+    return {
+        mode: 'release',
+        version: versionName,
+        targetPath: releasePath,
+        currentSymlink: currentSymlinkPath,
+        usedFallback,
+        warnings,
+    };
+}
+async function deployOverwrite(config, client, releasePackage, versionName) {
+    const warnings = [];
+    const tempPath = remoteJoin(config.target.path, config.target.tempDir);
+    const remoteArchivePath = remoteJoin(tempPath, `${versionName}.tgz`);
+    await client.exec(`mkdir -p ${shellQuote(config.target.path)} ${shellQuote(tempPath)}`);
+    await client.uploadFile(releasePackage.archivePath, remoteArchivePath);
+    const usedFallback = await publishPackageToRemotePath(config, client, remoteArchivePath, config.target.path, false);
+    await cleanupRemoteArchive(client, remoteArchivePath, warnings);
+    return {
+        mode: 'overwrite',
+        targetPath: config.target.path,
+        usedFallback,
+        warnings,
+    };
+}
+async function publishPackageToRemotePath(config, client, remoteArchivePath, remoteTargetPath, cleanBeforeFallback) {
+    if (!config.deploy.preferTar) {
+        await client.uploadDirectory(config.source.path, remoteTargetPath, config.source.exclude);
+        return true;
+    }
+    try {
+        await client.exec(`tar -xzf ${shellQuote(remoteArchivePath)} -C ${shellQuote(remoteTargetPath)}`);
+        return false;
+    }
+    catch (error) {
+        if (!config.deploy.fallbackToFileUpload) {
+            throw error;
+        }
+        if (cleanBeforeFallback) {
+            await client.exec(`rm -rf ${shellQuote(remoteTargetPath)} && mkdir -p ${shellQuote(remoteTargetPath)}`);
+        }
+        else {
+            await client.exec(`mkdir -p ${shellQuote(remoteTargetPath)}`);
+        }
+        await client.uploadDirectory(config.source.path, remoteTargetPath, config.source.exclude);
+        return true;
+    }
+}
+async function cleanupRemoteArchive(client, remoteArchivePath, warnings) {
+    try {
+        await client.exec(`rm -f ${shellQuote(remoteArchivePath)}`);
+    }
+    catch (error) {
+        warnings.push(`远程临时包清理失败: ${formatError(error)}`);
+    }
+}
+async function cleanupOldReleases(config, client, releasesPath, currentVersion, warnings) {
+    try {
+        const releases = await readRemoteReleaseNames(client, releasesPath);
+        const releasesToDelete = selectReleasesToDelete([...releases, currentVersion], currentVersion, config.deploy.keepReleases);
+        for (const release of releasesToDelete) {
+            await client.exec(`rm -rf ${shellQuote(remoteJoin(releasesPath, release))}`);
+        }
+    }
+    catch (error) {
+        warnings.push(`旧版本清理失败: ${formatError(error)}`);
+    }
+}
+async function ensureSourceExists(sourcePath) {
+    try {
+        await access(sourcePath);
+    }
+    catch {
+        throw new Error(`source.path 不存在: ${sourcePath}`);
+    }
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/remote.js

@@ -0,0 +1,38 @@
+import path from 'node:path';
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export function remoteJoin(...parts) {
+    return path.posix.join(...parts);
+}
+export async function readRemoteReleaseNames(client, releasesPath) {
+    const result = await client.exec(`if [ -d ${shellQuote(releasesPath)} ]; then for release_path in ${shellQuote(releasesPath)}/*; do [ -d "$release_path" ] || continue; basename "$release_path"; done; fi`);
+    return result.stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .sort();
+}
+export async function readRemoteReleaseEntries(client, releasesPath) {
+    const result = await client.exec(`if [ -d ${shellQuote(releasesPath)} ]; then for release_path in ${shellQuote(releasesPath)}/*; do [ -d "$release_path" ] || continue; version=$(basename "$release_path"); modified=$(stat -c %Y "$release_path" 2>/dev/null || stat -f %m "$release_path" 2>/dev/null || echo 0); printf '%s\\t%s\\n' "$version" "$modified"; done; fi`);
+    return result.stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const [version, modifiedAtSeconds = '0'] = line.split('\t');
+        return {
+            version,
+            modifiedAt: new Date(Number(modifiedAtSeconds) * 1000),
+        };
+    })
+        .sort((left, right) => left.version.localeCompare(right.version));
+}
+export async function readCurrentVersion(client, currentSymlinkPath) {
+    const result = await client.exec(`readlink ${shellQuote(currentSymlinkPath)} 2>/dev/null || true`);
+    const linkTarget = result.stdout.trim();
+    if (!linkTarget) {
+        return undefined;
+    }
+    return path.posix.basename(linkTarget);
+}

package/dist/rollback.js

@@ -0,0 +1,40 @@
+import { readCurrentVersion, readRemoteReleaseNames, remoteJoin, shellQuote, } from './remote.js';
+export function selectRollbackTarget(selection) {
+    const releases = [...new Set(selection.releases)].sort();
+    if (selection.requestedVersion) {
+        if (!releases.includes(selection.requestedVersion)) {
+            throw new Error(`回滚目标不存在: ${selection.requestedVersion}`);
+        }
+        return selection.requestedVersion;
+    }
+    const currentIndex = releases.indexOf(selection.currentVersion);
+    if (currentIndex === -1) {
+        throw new Error(`当前版本不存在: ${selection.currentVersion}`);
+    }
+    if (currentIndex === 0) {
+        throw new Error('没有可回滚版本');
+    }
+    return releases[currentIndex - 1];
+}
+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 targetVersion = selectRollbackTarget({
+        releases,
+        currentVersion,
+        requestedVersion,
+    });
+    await client.exec(`ln -sfn ${shellQuote(remoteJoin(config.target.releasesDir, targetVersion))} ${shellQuote(currentSymlinkPath)}`);
+    return {
+        version: targetVersion,
+        currentSymlink: currentSymlinkPath,
+    };
+}

package/dist/ssh.js

@@ -0,0 +1,139 @@
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { runProcess } from './process.js';
+import { remoteJoin, shellQuote } from './remote.js';
+export class ShellRemoteClient {
+    server;
+    constructor(server) {
+        this.server = server;
+    }
+    async exec(command) {
+        const spec = createSshProcessSpec(this.server, command);
+        return runProcess(spec.command, spec.args, { env: spec.env });
+    }
+    async uploadFile(localPath, remotePath) {
+        const spec = createScpProcessSpec(this.server, localPath, remotePath);
+        await runProcess(spec.command, spec.args, { env: spec.env });
+    }
+    async uploadDirectory(localPath, remotePath, exclude) {
+        await uploadDirectoryContents(this, localPath, remotePath, exclude);
+    }
+}
+export function createRemoteClient(config) {
+    return new ShellRemoteClient(config.server);
+}
+export function createScpRemoteTarget(destination, remotePath) {
+    return `${destination}:${remotePath}`;
+}
+export function createSshProcessSpec(server, remoteCommand) {
+    const destination = `${server.username}@${server.host}`;
+    if (server.password) {
+        return {
+            command: 'sshpass',
+            args: [
+                '-e',
+                'ssh',
+                '-p',
+                String(server.port),
+                '-o',
+                'StrictHostKeyChecking=accept-new',
+                '-o',
+                'PreferredAuthentications=password',
+                '-o',
+                'PubkeyAuthentication=no',
+                '-o',
+                'NumberOfPasswordPrompts=1',
+                destination,
+                remoteCommand,
+            ],
+            env: {
+                SSHPASS: server.password,
+            },
+        };
+    }
+    return {
+        command: 'ssh',
+        args: [
+            '-p',
+            String(server.port),
+            '-i',
+            requirePrivateKeyPath(server),
+            '-o',
+            'BatchMode=yes',
+            destination,
+            remoteCommand,
+        ],
+    };
+}
+export function createScpProcessSpec(server, localPath, remotePath) {
+    const destination = `${server.username}@${server.host}`;
+    if (server.password) {
+        return {
+            command: 'sshpass',
+            args: [
+                '-e',
+                'scp',
+                '-P',
+                String(server.port),
+                '-o',
+                'StrictHostKeyChecking=accept-new',
+                '-o',
+                'PreferredAuthentications=password',
+                '-o',
+                'PubkeyAuthentication=no',
+                '-o',
+                'NumberOfPasswordPrompts=1',
+                localPath,
+                createScpRemoteTarget(destination, remotePath),
+            ],
+            env: {
+                SSHPASS: server.password,
+            },
+        };
+    }
+    return {
+        command: 'scp',
+        args: [
+            '-P',
+            String(server.port),
+            '-i',
+            requirePrivateKeyPath(server),
+            '-o',
+            'BatchMode=yes',
+            localPath,
+            createScpRemoteTarget(destination, remotePath),
+        ],
+    };
+}
+function requirePrivateKeyPath(server) {
+    if (!server.privateKeyPath) {
+        throw new Error('server.privateKeyPath 或 server.password 必须配置一个');
+    }
+    return server.privateKeyPath;
+}
+async function uploadDirectoryContents(client, localPath, remotePath, exclude) {
+    const sourceStat = await stat(localPath);
+    if (!sourceStat.isDirectory()) {
+        await client.uploadFile(localPath, remoteJoin(remotePath, path.basename(localPath)));
+        return;
+    }
+    await walkDirectory(client, localPath, remotePath, exclude);
+}
+async function walkDirectory(client, localDirectory, remoteDirectory, exclude) {
+    await client.exec(`mkdir -p ${shellQuote(remoteDirectory)}`);
+    const entries = await readdir(localDirectory, { withFileTypes: true });
+    for (const entry of entries) {
+        if (exclude.includes(entry.name)) {
+            continue;
+        }
+        const localEntryPath = path.join(localDirectory, entry.name);
+        const remoteEntryPath = remoteJoin(remoteDirectory, entry.name);
+        if (entry.isDirectory()) {
+            await walkDirectory(client, localEntryPath, remoteEntryPath, exclude);
+            continue;
+        }
+        if (entry.isFile()) {
+            await client.uploadFile(localEntryPath, remoteEntryPath);
+        }
+    }
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.js

@@ -0,0 +1,102 @@
+import path from 'node:path';
+const dangerousTargetPaths = new Set([
+    '/',
+    '/home',
+    '/root',
+    '/var',
+    '/usr',
+    '/etc',
+    '/opt',
+    '/tmp',
+]);
+export function validateTargetPath(targetPath) {
+    if (!targetPath || !targetPath.trim()) {
+        throw new Error('target.path 不能为空');
+    }
+    const normalizedPath = path.posix.normalize(targetPath.trim());
+    if (!normalizedPath.startsWith('/')) {
+        throw new Error('target.path 必须是远程绝对路径');
+    }
+    if (dangerousTargetPaths.has(normalizedPath)) {
+        throw new Error(`危险远程路径: ${normalizedPath}`);
+    }
+    return normalizedPath;
+}
+export function normalizeConfig(input) {
+    const mode = input.deploy?.mode ?? 'release';
+    const compression = input.deploy?.compression ?? 'tgz';
+    const keepReleases = input.deploy?.keepReleases ?? 5;
+    const port = input.server?.port ?? 22;
+    const privateKeyPath = optionalString(input.server?.privateKeyPath);
+    const password = optionalString(input.server?.password);
+    if (mode !== 'release' && mode !== 'overwrite') {
+        throw new Error('deploy.mode 只支持 release 或 overwrite');
+    }
+    if (compression !== 'tgz') {
+        throw new Error('deploy.compression 第一版只支持 tgz');
+    }
+    if (!Number.isInteger(keepReleases) || keepReleases < 1) {
+        throw new Error('deploy.keepReleases 必须是正整数');
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error('server.port 必须是 1 到 65535 之间的整数');
+    }
+    const exclude = input.source?.exclude ?? [];
+    if (!Array.isArray(exclude)) {
+        throw new Error('source.exclude 必须是字符串数组');
+    }
+    if (exclude.some((entry) => typeof entry !== 'string')) {
+        throw new Error('source.exclude 必须是字符串数组');
+    }
+    if (!privateKeyPath && !password) {
+        throw new Error('server.privateKeyPath 或 server.password 必须配置一个');
+    }
+    return {
+        source: {
+            path: requiredString(input.source?.path, 'source.path'),
+            exclude,
+        },
+        server: {
+            host: requiredString(input.server?.host, 'server.host'),
+            port,
+            username: requiredString(input.server?.username, 'server.username'),
+            privateKeyPath,
+            password,
+        },
+        target: {
+            path: validateTargetPath(requiredString(input.target?.path, 'target.path')),
+            currentSymlink: validateTargetName(input.target?.currentSymlink ?? 'current', 'target.currentSymlink'),
+            releasesDir: validateTargetName(input.target?.releasesDir ?? 'releases', 'target.releasesDir'),
+            tempDir: validateTargetName(input.target?.tempDir ?? '.ssh-release-tmp', 'target.tempDir'),
+        },
+        deploy: {
+            mode: mode,
+            keepReleases,
+            compression: compression,
+            preferTar: input.deploy?.preferTar ?? true,
+            fallbackToFileUpload: input.deploy?.fallbackToFileUpload ?? true,
+        },
+    };
+}
+function requiredString(value, fieldName) {
+    if (!value || !value.trim()) {
+        throw new Error(`${fieldName} 不能为空`);
+    }
+    return value.trim();
+}
+function optionalString(value) {
+    if (!value || !value.trim()) {
+        return undefined;
+    }
+    return value.trim();
+}
+function validateTargetName(value, fieldName) {
+    const normalizedValue = requiredString(value, fieldName);
+    if (normalizedValue === '.' ||
+        normalizedValue === '..' ||
+        normalizedValue.includes('/') ||
+        normalizedValue.includes('\\')) {
+        throw new Error(`${fieldName} 必须是简单相对名称`);
+    }
+    return normalizedValue;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "ssh-release",
+  "version": "0.1.0",
+  "description": "A general-purpose SSH file release CLI.",
+  "type": "module",
+  "bin": {
+    "ssh-release": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run lint && npm test && npm run build"
+  },
+  "keywords": [
+    "ssh",
+    "release",
+    "deploy",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JackEngineer/ssh-release.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JackEngineer/ssh-release/issues"
+  },
+  "homepage": "https://github.com/JackEngineer/ssh-release#readme",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.19.1",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  }
+}