@akairos/code-deploy 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aatrox
+
+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

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# Deploy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+基于 Ink 8、React 和 `@inkjs/ui`，把本地目录 A 的内容发布到 SSH 服务器目录 B。支持直接发布已有内容，或先执行自定义构建命令。工具不包含任何业务环境、服务器或分支预设；真实配置仅存用户目录。
+
+## 启动
+
+需要 Node.js 22+、pnpm、本地 `ssh`、`scp`、`tar`、`find`。启用 Git 检查或分支锁时需要 `git`。远端需要 POSIX shell 和常用文件命令。
+
+```sh
+pnpm install
+pnpm build
+npm link
+code-deploy
+```
+
+TUI 使用左侧环境导航和主工作区。按 `n` 新建，`e` 编辑；配置表单左侧显示字段和草稿值，右侧编辑当前项。方向键、Tab 选择字段，Enter 编辑或切换开关，Ctrl+S 保存整份配置，Esc 取消当前编辑或丢弃草稿。表单超过窗口时滚动，已填内容保留且可以回看。输入 `/` 可使用 `/new`、`/config`、`/deploy`、`/check`、`/environments` 和 `/quit`。
+
+## 源目录与三个锁
+
+实际源目录 A 是**启动工具时的当前目录**，工具不会隐式切换到另一个项目。`projectDir` 保存需要绑定的本地目录。
+
+| 配置 | 开启后行为 | 默认 |
+| --- | --- | --- |
+| 锁定本地目录 | 当前目录必须等于配置的 A；子目录不算，真实路径相同的符号链接视为同一目录 | 关闭 |
+| 锁定发布分支 | 当前 Git 分支必须等于 `expectedBranch`，否则直接拒绝 | 关闭 |
+| 锁定映射关系 | 在 A 中显式开启，记录真实目录、当前分支、服务器及 B 的快照；发布时逐项匹配 | 关闭 |
+| Git 状态检查 | 刷新上游引用，发现 Git 异常后等待明确确认 | 开启 |
+
+三个锁独立配置。映射锁包含目录和分支的约束，即使另外两个开关关闭也会检查；锁定项不匹配时不能用确认警告绕过。修改映射绑定项前必须解除映射锁，修改后在正确目录和分支重新开启。用户配置内已开启的映射必须一一对应，同一个目录和分支不能绑定两个远程目标，同一个远程目标也不能绑定不同的目录和分支。服务器以配置中的 host、账号、端口识别；指向同一服务器的不同 SSH 别名不自动合并。
+
+旧配置按此前行为迁移：开启目录锁；原来填写了分支要求的配置开启分支锁；Git 检查默认开启。现有服务器、目录及密码来源继续保留在用户配置中。
+
+## Git 检查与确认
+
+正式发布前使用当前分支的 upstream 执行 `git fetch --no-tags`，不执行 pull、merge 或 checkout。检查暂存、未暂存、未跟踪文件，以及落后或领先上游的提交。无 Git 仓库、detached HEAD、缺少上游或 fetch 失败也会明确提醒，不能当作“干净且同步”。
+
+有提醒时，在执行构建和上传前显示详情并等待 `[y/N]`；默认取消。TUI 可用 PgUp/PgDn 查看长提醒。确认后再次检查目录、分支、HEAD 和 Git 状态，发生变化时重新确认。构建结束、上传之前再次核验目录、分支和 HEAD，变化则拒绝。用户仍应避免在发布期间同时修改源文件。
+
+```sh
+code-deploy list
+code-deploy example
+code-deploy check example
+code-deploy deploy example --yes
+code-deploy config
+code-deploy init /absolute/path/config.json
+```
+
+`--yes` 仅确认“开始发布”，不跳过 Git 异常确认。非交互执行遇到 Git 提醒时退出失败，不会构建或上传。`check` 会检查本地规则和 Git 状态，并只读列出远程目录；它可能 fetch，但不发布文件。
+
+## 配置与密码
+
+配置默认为 `~/.config/code-deploy/config.json`，权限 `600`；`CODE_DEPLOY_CONFIG` 可指定其他文件。项目内的 `config.example.json` 仅是虚构示例，不在启动时自动导入。首次可通过 `init` 导入；已有配置不会被覆盖。
+
+`buildCommand` 留空表示跳过构建，否则通过 `/bin/sh` 在 A 执行用户信任的命令。`outputDir` 是 A 内的相对路径：`.` 表示 A 本身，`dist` 表示 A/dist。不要求 `index.html`，可以发布任意非空目录。直接发布 `.` 时会包含隐藏文件和 `.git` 等实际存在的内容，请选择真正需要发布的目录；本工具不内置排除规则。
+
+默认使用现有 SSH 密钥 / Agent，沿用 `~/.ssh/config`。也支持配置密码环境变量名，或在 TUI 中显式将密码保存到系统钥匙串。JSON 不存密码，密码不会作为命令行参数传递。钥匙串条目绑定环境标识、服务器、账号及端口；修改目标后需要重新保存。Linux 无持久凭据服务时建议使用环境变量或 SSH 密钥。
+
+## 发布方式
+
+上传临时压缩包后，在 B 同级目录完整解压，校验非空，然后把旧 B 改名为 `.<目录名>.backup-<uuid>`，再切换新 B。切换失败时尝试恢复旧目录，备份需要按需手工清理。使用同级锁目录避免本工具实例同时切换同一目标。
+
+这是目录整体替换，B 中原来存在的其他文件会进入备份而不进入新目录。目标需要至少两级绝对路径，不能是常见系统目录或符号链接；发布内容也不能含符号链接。需要 B 的父目录写权限；两次重命名之间有短暂间隔，容器挂载点等特殊目录需先确认兼容。远端异常退出可能留下锁或临时压缩包；取消后应确认实际版本。
+
+## 验证
+
+```sh
+pnpm build
+pnpm test
+```
+
+测试只使用临时目录、本地 bare Git 仓库和模拟 SSH，覆盖目录/分支/映射锁、旧配置迁移、Git fetch 与异常确认、完整发布、备份恢复、取消及 TUI 表单交互，不发布真实服务器。

package/dist/app.js

@@ -0,0 +1,215 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { Box, Text, useApp, useInput, useStdout } from "ink";
+import { ConfirmInput, Spinner, TextInput, ThemeProvider, defaultTheme, extendTheme } from "@inkjs/ui";
+import { configFile, saveConfig } from "./config.js";
+import { deletePassword } from "./credentials.js";
+import { checkServer, deploy, steps } from "./deploy.js";
+import { inspectProject } from "./preflight.js";
+import { Settings, colors, authNames } from "./settings.js";
+const theme = extendTheme(defaultTheme, { components: {
+        Spinner: { styles: { frame: () => ({ color: colors.accent }) } }
+    } });
+const message = (error) => error instanceof Error ? error.message : String(error);
+const formatDuration = (ms) => ms < 60_000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`;
+// 目录只留最后两级，帮助辨认目标。
+const shortDir = (dir) => `…/${dir.split("/").filter(Boolean).slice(-2).join("/")}`;
+// 源目录和实际分支放在配置旁边，发布前能直接核对 A → B。
+function Summary({ profile, project }) {
+    const rows = [
+        ["源目录 A", profile.lockDirectory || profile.lockMapping ? profile.projectDir : `${process.cwd()}（启动目录）`],
+        ["Git 状态", project], ["远程目录 B", `${profile.user}@${profile.host}:${profile.port}${profile.remoteDir}`],
+        ["构建命令", profile.buildCommand || "跳过构建，直接发布"], ["发布内容", profile.outputDir],
+        ["登录方式", `${authNames[profile.auth]}${profile.auth === "env" ? ` · ${profile.passwordEnv}` : ""}`],
+        ["目录锁", profile.lockDirectory ? `开启 · ${profile.projectDir}` : "关闭"],
+        ["分支锁", profile.lockBranch ? `开启 · ${profile.expectedBranch}` : "关闭"],
+        ["映射锁", profile.lockMapping ? `开启 · ${profile.mapping ? shortDir(profile.mapping.remoteDir) : "未绑定"}` : "关闭"],
+        ["Git 检查", profile.checkGit ? "开启 · 异常需确认" : "关闭"]
+    ];
+    return _jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { bold: true, color: colors.warm, children: [profile.name, " ", _jsxs(Text, { color: colors.muted, children: ["/ ", profile.id] })] }), rows.map(([label, value]) => _jsxs(Box, { children: [_jsx(Box, { width: 11, flexShrink: 0, children: _jsx(Text, { color: colors.muted, children: label }) }), _jsx(Box, { flexGrow: 1, minWidth: 0, children: _jsx(Text, { wrap: "truncate", children: value }) })] }, label))] });
+}
+// 纵向环境列表 + 下方摘要；每行带服务器和目录简写，↑↓ 选择。
+export function App({ initialConfig, initialId }) {
+    const { exit } = useApp();
+    const { stdout: output } = useStdout();
+    const stdout = output;
+    const [size, setSize] = useState({ columns: stdout.columns || 110, rows: stdout.rows || 32 });
+    const [config, setConfig] = useState(initialConfig);
+    const [index, setIndex] = useState(Math.max(0, initialConfig.profiles.findIndex(profile => profile.id === initialId)));
+    const [screen, setScreen] = useState("dashboard");
+    const [creating, setCreating] = useState(false);
+    const [notice, setNotice] = useState("");
+    const [project, setProject] = useState("读取中…");
+    const [command, setCommand] = useState(false);
+    const [job, setJob] = useState();
+    const [gitPrompt, setGitPrompt] = useState();
+    const [warningOffset, setWarningOffset] = useState(0);
+    const [previewOffset, setPreviewOffset] = useState(0);
+    const [seed, setSeed] = useState();
+    const controller = useRef(undefined);
+    const confirmGit = useRef(undefined);
+    const profile = config.profiles[index];
+    useEffect(() => {
+        const resize = () => setSize({ columns: stdout.columns || 110, rows: stdout.rows || 32 });
+        stdout.on("resize", resize);
+        return () => { stdout.off("resize", resize); controller.current?.abort(); confirmGit.current?.(false); };
+    }, [stdout]);
+    useEffect(() => {
+        if (!profile || screen === "settings")
+            return;
+        const abort = new AbortController();
+        setProject("读取中…");
+        inspectProject(profile, abort.signal).then(state => {
+            if (!abort.signal.aborted)
+                setProject(`${state.branch || "无分支"} · ${state.commit.slice(0, 8) || "无提交"}${state.changes ? " · 有未提交修改" : ""}`);
+        }).catch(error => { if (!abort.signal.aborted)
+            setProject(message(error)); });
+        return () => abort.abort();
+    }, [profile, screen]);
+    // 复制配置时解除映射锁：新环境通常要改目标，映射锁会挡住编辑。
+    function openSettings(isNew, source) {
+        setSeed(source ? { ...source, id: "", name: `${source.name} 副本`, lockMapping: false, mapping: undefined } : undefined);
+        setCreating(isNew);
+        setScreen("settings");
+        setNotice("");
+    }
+    async function persist(next) { await saveConfig(next); setConfig(next); }
+    function answerGit(value) { confirmGit.current?.(value); confirmGit.current = undefined; setGitPrompt(undefined); }
+    function startJob(connectionOnly) {
+        if (!profile)
+            return;
+        const abort = new AbortController();
+        controller.current = abort;
+        setJob({ title: connectionOnly ? "检查服务器" : "发布目录", step: 0, logs: "", status: "running", started: Date.now() });
+        setNotice("");
+        setScreen("job");
+        const append = (text) => setJob(current => current && ({ ...current, logs: (current.logs + text).slice(-60_000) }));
+        const task = connectionOnly ? checkServer(profile, abort.signal).then(text => append(`${text}\n`))
+            : deploy(profile, event => {
+                if (event.type === "step")
+                    setJob(current => current && ({ ...current, step: event.index }));
+                else
+                    append(event.text);
+            }, abort.signal, state => new Promise(resolve => {
+                setGitPrompt(state);
+                setWarningOffset(0);
+                const cancel = () => answerGit(false);
+                confirmGit.current = value => { abort.signal.removeEventListener("abort", cancel); resolve(value); };
+                abort.signal.addEventListener("abort", cancel, { once: true });
+                if (abort.signal.aborted)
+                    cancel();
+            }));
+        void task.then(() => setJob(current => current && ({ ...current, status: "success", elapsed: Date.now() - current.started })))
+            .catch(error => { append(`\n${message(error)}\n`); setJob(current => current && ({ ...current, status: "error", elapsed: Date.now() - current.started })); });
+    }
+    function execute(value) {
+        setCommand(false);
+        setNotice("");
+        const action = value.trim().replace(/^\//, "");
+        if (action === "new")
+            openSettings(true);
+        else if (action === "quit")
+            exit();
+        else if (action === "environments")
+            setScreen("dashboard");
+        else if (!profile)
+            setNotice("请先新建或选择发布配置");
+        else if (action === "config")
+            openSettings(false);
+        else if (action === "copy")
+            openSettings(true, profile);
+        else if (action === "deploy")
+            setScreen("confirm");
+        else if (action === "check")
+            startJob(true);
+        else
+            setNotice("可用命令：/new /config /deploy /check /environments /quit");
+    }
+    const summaryLines = 11; // Summary 标题 + 10 行
+    const previewHeight = Math.max(4, size.rows - (screen === "dashboard" ? 7 : 12));
+    const previewMaxOffset = Math.max(0, summaryLines - previewHeight);
+    useInput((input, key) => {
+        if (key.ctrl && input === "c") {
+            if (screen === "job" && job?.status === "running")
+                controller.current?.abort();
+            else
+                exit();
+            return;
+        }
+        if (screen === "settings")
+            return;
+        if (gitPrompt && (key.pageDown || key.pageUp)) {
+            const maximum = Math.max(0, gitPrompt.warnings.join("\n\n").split("\n").length - Math.max(3, size.rows - 15));
+            setWarningOffset(current => Math.max(0, Math.min(maximum, current + (key.pageDown ? 5 : -5))));
+        }
+        if ((key.pageDown || key.pageUp) && (screen === "dashboard" || screen === "confirm" || screen === "delete")) {
+            setPreviewOffset(current => Math.max(0, Math.min(previewMaxOffset, current + (key.pageDown ? 4 : -4))));
+        }
+        if (command) {
+            if (key.escape)
+                setCommand(false);
+            return;
+        }
+        if (key.escape) {
+            if (gitPrompt)
+                answerGit(false);
+            else if (screen === "job" && job?.status === "running")
+                controller.current?.abort();
+            else {
+                setScreen("dashboard");
+                setNotice("");
+            }
+            return;
+        }
+        if (screen !== "dashboard")
+            return;
+        if (input === "/") {
+            setCommand(true);
+            return;
+        }
+        if (input === "n") {
+            openSettings(true);
+            return;
+        }
+        if (key.upArrow) {
+            setIndex(Math.max(0, index - 1));
+            setPreviewOffset(0);
+        }
+        if (key.downArrow) {
+            setIndex(Math.min(config.profiles.length - 1, index + 1));
+            setPreviewOffset(0);
+        }
+        if (!profile)
+            return;
+        if (input === "e")
+            openSettings(false);
+        else if (input === "c")
+            startJob(true);
+        else if (input === "x")
+            setScreen("delete");
+        else if (input === "d")
+            openSettings(true, profile);
+        else if (key.return)
+            setScreen("confirm");
+    });
+    return _jsx(ThemeProvider, { theme: theme, children: _jsxs(Box, { flexDirection: "column", paddingX: 1, width: size.columns, children: [_jsxs(Box, { justifyContent: "space-between", children: [_jsx(Text, { bold: true, color: colors.accent, children: (screen === "confirm" || screen === "delete" || screen === "job") && profile ? profile.name : "code-deploy" }), _jsx(Text, { color: colors.muted, children: "v0.2" })] }), screen !== "settings" && screen !== "job" && _jsxs(Box, { marginTop: 1, children: [screen === "dashboard" && _jsxs(Box, { flexDirection: "column", width: 48, flexShrink: 0, paddingRight: 1, children: [config.profiles.map((item, offset) => _jsxs(Box, { children: [_jsx(Box, { width: 2, flexShrink: 0, children: _jsx(Text, { color: offset === index ? colors.accent : undefined, children: offset === index ? "›" : "" }) }), _jsx(Box, { width: 14, flexShrink: 0, children: _jsx(Text, { bold: offset === index, color: offset === index ? colors.accent : undefined, wrap: "truncate", children: item.name }) }), _jsx(Box, { flexGrow: 1, minWidth: 0, children: _jsxs(Text, { color: colors.muted, wrap: "truncate", children: [item.user, "@", item.host, " ", shortDir(item.remoteDir)] }) })] }, item.id)), !config.profiles.length && _jsx(Text, { color: colors.muted, children: "\u6682\u65E0\u914D\u7F6E \u00B7 \u6309 n \u65B0\u5EFA" })] }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, minWidth: 0, paddingLeft: 2, borderStyle: screen === "dashboard" ? "single" : undefined, borderTop: false, borderBottom: false, borderRight: false, borderColor: colors.muted, children: [profile && _jsxs(_Fragment, { children: [_jsx(Box, { height: previewHeight, overflow: "hidden", flexDirection: "column", children: _jsx(Box, { marginTop: -previewOffset, flexDirection: "column", children: _jsx(Summary, { profile: profile, project: project }) }) }), previewMaxOffset > 0 && _jsxs(Text, { color: colors.muted, children: ["PgUp / PgDn \u6EDA\u52A8\u9884\u89C8 ", previewOffset > 0 ? "↑" : "", previewOffset < previewMaxOffset ? "↓" : ""] })] }), screen === "dashboard" && !profile && _jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(Text, { bold: true, children: "\u914D\u7F6E\u4E00\u6B21\uFF0C\u9009\u62E9\u53D1\u5E03" }), _jsx(Text, { children: "\u586B\u5199\u672C\u5730\u6E90\u76EE\u5F55\u3001\u670D\u52A1\u5668\u548C\u8FDC\u7A0B\u76EE\u5F55\uFF0C\u6309\u9700\u5F00\u542F\u9501\u5B9A\u89C4\u5219\u3002" }), _jsx(Text, { color: colors.accent, children: "\u6309 n \u65B0\u5EFA\uFF0C\u6216\u8F93\u5165 /new\u3002" })] }), screen === "confirm" && _jsxs(_Fragment, { children: [_jsx(Text, { color: colors.warm, children: "\u53D1\u5E03\u524D\u5C06\u68C0\u67E5\u9501\u5B9A\u89C4\u5219\u548C Git \u72B6\u6001\uFF0C\u518D\u66FF\u6362\u8FDC\u7A0B\u76EE\u5F55 B\u3002" }), _jsx(Text, { children: "\u786E\u8BA4\u53D1\u5E03\uFF1F [y/N]" }), _jsx(ConfirmInput, { defaultChoice: "cancel", onConfirm: () => startJob(false), onCancel: () => setScreen("dashboard") })] }), screen === "delete" && profile && _jsxs(_Fragment, { children: [_jsx(Text, { color: colors.warm, children: "\u5220\u9664\u914D\u7F6E\u53CA\u5173\u8054\u5BC6\u7801\uFF1F\u670D\u52A1\u5668\u6587\u4EF6\u4E0D\u53D8\u3002[y/N]" }), _jsx(ConfirmInput, { defaultChoice: "cancel", onCancel: () => setScreen("dashboard"), onConfirm: () => {
+                                                void (async () => {
+                                                    await deletePassword(profile);
+                                                    await persist({ version: 1, profiles: config.profiles.filter(item => item.id !== profile.id) });
+                                                    setIndex(Math.max(0, index - 1));
+                                                    setScreen("dashboard");
+                                                })().catch(error => setNotice(message(error)));
+                                            } })] })] })] }), screen === "settings" && _jsx(Box, { flexDirection: "column", paddingLeft: 2, marginTop: 1, children: _jsx(Settings, { config: config, profile: creating ? undefined : profile, initial: creating ? seed : undefined, onCancel: () => { setSeed(undefined); setScreen("dashboard"); }, onSave: async (next) => {
+                            const profiles = creating ? [...config.profiles, next] : config.profiles.map(item => item.id === next.id ? next : item);
+                            await persist({ version: 1, profiles });
+                            setIndex(profiles.findIndex(item => item.id === next.id));
+                            setSeed(undefined);
+                            setScreen("dashboard");
+                            setNotice("配置已保存");
+                        } }, creating ? `new-${seed?.name || "blank"}` : profile?.id) }), screen === "job" && job && _jsxs(Box, { flexDirection: "column", paddingLeft: 2, marginTop: 1, children: [_jsx(Text, { bold: true, color: colors.warm, children: job.title }), gitPrompt ? _jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(Text, { color: colors.warm, children: "Git \u72B6\u6001\u9700\u8981\u786E\u8BA4\uFF0C\u5C1A\u672A\u6267\u884C\u6784\u5EFA\u6216\u4E0A\u4F20" }), _jsxs(Text, { children: [gitPrompt.directory, " \u00B7 ", gitPrompt.branch || "无分支"] }), _jsx(Box, { height: Math.max(3, size.rows - 15), overflow: "hidden", children: _jsx(Text, { children: gitPrompt.warnings.join("\n\n").split("\n").slice(warningOffset, warningOffset + Math.max(3, size.rows - 15)).join("\n") }) }), _jsx(Text, { color: colors.muted, children: "PgUp / PgDn \u6EDA\u52A8\u67E5\u770B Git \u63D0\u9192" }), _jsx(Text, { children: "\u4ECD\u8981\u4F7F\u7528\u5F53\u524D\u672C\u5730\u5185\u5BB9\u53D1\u5E03\uFF1F [y/N]" }), _jsx(ConfirmInput, { defaultChoice: "cancel", onConfirm: () => answerGit(true), onCancel: () => answerGit(false) })] }) : _jsxs(_Fragment, { children: [_jsx(Box, { gap: 2, flexWrap: "wrap", children: steps.map((label, step) => {
+                                        const done = job.status === "success" || step < job.step;
+                                        const failed = job.status === "error" && step === job.step;
+                                        const active = job.status === "running" && step === job.step;
+                                        return _jsxs(Box, { gap: 1, children: [done ? _jsx(Text, { color: colors.good, children: "\u2713" }) : failed ? _jsx(Text, { color: colors.error, children: "\u2717" }) : active ? _jsx(Spinner, {}) : _jsx(Text, { color: colors.muted, children: "\u00B7" }), _jsx(Text, { color: done ? colors.good : failed ? colors.error : active ? colors.accent : colors.muted, children: label })] }, label);
+                                    }) }), _jsx(Box, { flexDirection: "column", height: Math.max(5, size.rows - 12), overflow: "hidden", marginY: 1, children: _jsx(Text, { wrap: "truncate", children: job.logs.split("\n").slice(-Math.max(3, size.rows - 14)).join("\n") || "正在检查…" }) }), job.status === "running" ? _jsx(Spinner, { label: "\u6267\u884C\u4E2D \u00B7 Ctrl+C \u53D6\u6D88" }) : _jsxs(_Fragment, { children: [_jsx(Text, { color: job.status === "success" ? colors.good : colors.error, children: job.status === "success" ? `✓ 执行完成 · 用时 ${formatDuration(job.elapsed ?? 0)}` : `执行失败 / 已取消 · 用时 ${formatDuration(job.elapsed ?? 0)}` }), _jsx(Text, { color: colors.accent, children: "\u6309 Esc \u8FD4\u56DE" })] })] })] }), notice && _jsx(Text, { color: colors.warm, children: notice }), _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [command && _jsxs(Box, { children: [_jsx(Text, { color: colors.accent, children: "/ " }), _jsx(TextInput, { placeholder: "new \u00B7 config \u00B7 deploy \u00B7 check \u00B7 environments \u00B7 quit", onSubmit: execute })] }), (screen === "dashboard" || screen === "confirm" || screen === "delete") && _jsx(Text, { color: colors.muted, wrap: "truncate", children: "\u2191\u2193 \u9009\u62E9 \u00B7 Enter \u53D1\u5E03 \u00B7 e \u7F16\u8F91 \u00B7 c \u68C0\u67E5 \u00B7 x \u5220\u9664 \u00B7 d \u590D\u5236 \u00B7 n \u65B0\u5EFA \u00B7 / \u547D\u4EE4" }), _jsx(Text, { color: colors.muted, wrap: "truncate", children: configFile })] })] }) });
+}

package/dist/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline/promises";
+import { render } from "ink";
+import { App } from "./app.js";
+import { configFile, loadConfig, saveConfig } from "./config.js";
+import { checkServer, deploy, steps } from "./deploy.js";
+import { inspectProject } from "./preflight.js";
+const help = `DEPLOY · 本地目录 A → 服务器目录 B
+
+用法：
+  code-deploy                         打开交互界面
+  code-deploy <环境标识>              打开指定环境
+  code-deploy list                    列出环境
+  code-deploy check <环境标识>        检查锁定规则、Git 状态和远程目录
+  code-deploy deploy <环境标识> --yes  按配置构建并部署
+  code-deploy config                  显示配置文件路径
+  code-deploy init <配置文件>         首次导入环境配置，不覆盖已有环境
+
+选项：
+  -y, --yes    确认发布，Git 异常仍须交互确认
+  -h, --help   显示帮助
+
+可使用 CODE_DEPLOY_CONFIG 指定其他配置文件。密码不写入 JSON。
+`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        options: { help: { type: "boolean", short: "h" }, yes: { type: "boolean", short: "y" } },
+        allowPositionals: true
+    });
+    if (values.help) {
+        console.log(help);
+        return;
+    }
+    const [command, id] = positionals;
+    if (command === "config") {
+        console.log(configFile);
+        return;
+    }
+    let config = await loadConfig();
+    if (command === "init") {
+        if (!id)
+            throw new Error("用法：code-deploy init <配置文件>");
+        if (config.profiles.length)
+            throw new Error("已有环境配置，请通过 TUI 编辑，避免覆盖");
+        config = await loadConfig(id);
+        if (!config.profiles.length)
+            throw new Error("导入文件不存在或没有环境配置");
+        await saveConfig(config);
+        console.log(`已导入 ${config.profiles.length} 个环境：${configFile}`);
+        return;
+    }
+    if (command === "list") {
+        if (!config.profiles.length)
+            console.log("暂无环境，运行 code-deploy 新建。");
+        for (const profile of config.profiles) {
+            console.log(`${profile.id}  ${profile.name}\n  A: ${profile.lockDirectory || profile.lockMapping ? profile.projectDir : "启动目录"}\n  B: ${profile.user}@${profile.host}:${profile.port}${profile.remoteDir}\n  目录锁: ${profile.lockDirectory} · 分支锁: ${profile.lockBranch ? profile.expectedBranch : "关闭"} · 映射锁: ${profile.lockMapping} · Git 检查: ${profile.checkGit}\n`);
+        }
+        return;
+    }
+    if (command === "check" || command === "deploy") {
+        const profile = config.profiles.find(item => item.id === id);
+        if (!profile)
+            throw new Error(`找不到环境 ${id || "（未指定）"}，运行 code-deploy list 查看`);
+        if (command === "deploy" && !values.yes) {
+            if (process.stdin.isTTY && process.stdout.isTTY) {
+                await render(_jsx(App, { initialConfig: config, initialId: id }), { alternateScreen: true, exitOnCtrlC: false }).waitUntilExit();
+                return;
+            }
+            throw new Error("非交互发布需要 --yes 明确确认；发布将替换配置的远程目录");
+        }
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        process.once("SIGINT", abort);
+        process.once("SIGTERM", abort);
+        try {
+            if (command === "check") {
+                const project = await inspectProject(profile, controller.signal, profile.checkGit);
+                console.log(`${project.directory}\n${project.branch || "无分支"} · ${project.commit.slice(0, 10) || "无提交"}`);
+                if (project.warnings.length)
+                    console.log(`Git 状态提醒：\n${project.warnings.join("\n\n")}`);
+                console.log(await checkServer(profile, controller.signal));
+            }
+            else {
+                console.log(`发布 ${profile.name}\nA: ${process.cwd()}\nB: ${profile.user}@${profile.host}:${profile.port}${profile.remoteDir}`);
+                const started = Date.now();
+                await deploy(profile, event => {
+                    if (event.type === "step")
+                        console.log(`\n[${event.index + 1}/${steps.length}] ${event.text}`);
+                    else
+                        process.stdout.write(event.text);
+                }, controller.signal, process.stdin.isTTY && process.stdout.isTTY ? async (state) => {
+                    console.log(`\nGit 状态需要确认：\n${state.warnings.join("\n\n")}`);
+                    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+                    try {
+                        const answer = await prompt.question("仍使用当前本地内容发布？ [y/N] ", { signal: controller.signal });
+                        return answer.trim().toLowerCase() === "y";
+                    }
+                    finally {
+                        prompt.close();
+                    }
+                } : undefined);
+                console.log(`\n部署完成，用时 ${((Date.now() - started) / 1000).toFixed(1)}s。`);
+            }
+        }
+        finally {
+            process.off("SIGINT", abort);
+            process.off("SIGTERM", abort);
+        }
+        return;
+    }
+    if (command && !config.profiles.some(profile => profile.id === command))
+        throw new Error(`未知命令或环境：${command}\n${help}`);
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.log(help);
+        return;
+    }
+    await render(_jsx(App, { initialConfig: config, initialId: command }), { alternateScreen: true, exitOnCtrlC: false }).waitUntilExit();
+}
+main().catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

package/dist/config.js

@@ -0,0 +1,105 @@
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+// 配置文件独立于项目，切换工作目录不会改变环境列表。
+export const configFile = process.env.CODE_DEPLOY_CONFIG || path.join(homedir(), ".config/code-deploy/config.json");
+const singleLine = z.string().refine(value => !/[\x00-\x1f\x7f]/.test(value), "不能包含控制字符");
+// 拒绝根目录、系统目录及带跳转的路径，降低误覆盖风险。
+export function isSafeRemoteDir(value) {
+    const parts = value.split("/").filter(Boolean);
+    return value.startsWith("/") && parts.length >= 2 &&
+        !/[\x00-\x1f\x7f]/.test(value) && !parts.some(part => part === "." || part === "..") &&
+        !["bin", "sbin", "etc", "usr", "lib", "lib64", "proc", "sys", "dev", "boot", "run"].includes(parts[0]);
+}
+const mappingSchema = z.object({
+    projectDir: singleLine.refine(path.isAbsolute), branch: singleLine.min(1),
+    host: singleLine.min(1), user: singleLine.min(1), port: z.number().int().min(1).max(65535),
+    remoteDir: z.string().refine(isSafeRemoteDir)
+});
+export const profileSchema = z.object({
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "环境标识只能使用小写字母、数字和连字符"),
+    name: singleLine.min(1, "请输入环境名称"),
+    projectDir: singleLine.refine(path.isAbsolute, "本地目录必须是绝对路径"),
+    host: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/, "请输入 IP、主机名或 SSH 别名"),
+    user: z.string().regex(/^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/, "请输入服务器账号"),
+    port: z.number().int().min(1).max(65535),
+    remoteDir: z.string().refine(isSafeRemoteDir, "远程目录必须是至少两级的绝对路径，且不能是系统目录"),
+    buildCommand: singleLine,
+    outputDir: singleLine.min(1).refine(value => !path.isAbsolute(value) && !value.split(/[\\/]/).includes(".."), "发布内容必须是源目录内的相对路径，或使用 . 发布源目录本身"),
+    expectedBranch: singleLine,
+    auth: z.enum(["env", "keychain", "ssh"]),
+    passwordEnv: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "环境变量名称无效"),
+    lockDirectory: z.boolean().default(false),
+    lockBranch: z.boolean().default(false),
+    lockMapping: z.boolean().default(false),
+    checkGit: z.boolean().default(true),
+    mapping: mappingSchema.optional()
+});
+const configSchema = z.object({ version: z.literal(1), profiles: z.array(profileSchema) }).superRefine((data, context) => {
+    if (new Set(data.profiles.map(profile => profile.id)).size !== data.profiles.length) {
+        context.addIssue({ code: "custom", message: "环境标识不能重复", path: ["profiles"] });
+    }
+    for (const profile of data.profiles) {
+        if (profile.lockBranch && !profile.expectedBranch)
+            context.addIssue({ code: "custom", message: `${profile.name}：开启分支锁时必须填写指定分支` });
+        if (!profile.lockMapping)
+            continue;
+        const mapping = profile.mapping;
+        if (!mapping || path.resolve(profile.projectDir) !== path.resolve(mapping.projectDir) ||
+            targetKey(profile) !== targetKey(mapping)) {
+            context.addIssue({ code: "custom", message: `${profile.name}：配置与锁定映射不一致，请先解除映射锁再修改` });
+        }
+        for (const other of data.profiles) {
+            if (other.id === profile.id || !other.lockMapping || !other.mapping || !mapping)
+                continue;
+            const sameSource = path.resolve(mapping.projectDir) === path.resolve(other.mapping.projectDir);
+            const sameTarget = targetKey(mapping) === targetKey(other.mapping);
+            if (sameSource !== sameTarget)
+                context.addIssue({ code: "custom", message: `${profile.name} 与 ${other.name} 的锁定映射不是一一对应` });
+        }
+    }
+});
+// 服务器和目录共同标识远程目标，规范化末尾斜线。
+export function targetKey(target) {
+    return JSON.stringify([target.host, target.user, target.port, path.posix.normalize(target.remoteDir).replace(/\/$/, "")]);
+}
+// 旧配置曾固定从 projectDir 构建，迁移时显式保留这一约束。
+function migrateConfig(value) {
+    if (!value || typeof value !== "object" || !("profiles" in value) || !Array.isArray(value.profiles))
+        return value;
+    return { ...value, profiles: value.profiles.map(profile => ({
+            ...profile,
+            lockDirectory: profile.lockDirectory ?? true,
+            lockBranch: profile.lockBranch ?? Boolean(profile.expectedBranch)
+        })) };
+}
+// 只将“文件不存在”视为空配置，避免损坏配置被悄悄覆盖。
+export async function loadConfig(file = configFile) {
+    try {
+        return configSchema.parse(migrateConfig(JSON.parse(await readFile(file, "utf8"))));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { version: 1, profiles: [] };
+        throw new Error(`读取配置失败 ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function saveConfig(config, file = configFile) {
+    const parsed = configSchema.parse(config);
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, file);
+    await chmod(file, 0o600);
+}
+// 新配置使用通用默认值，服务器、目录和分支均由用户填写。
+export function newProfile() {
+    return {
+        id: "", name: "", projectDir: process.cwd(), host: "", user: process.env.USER || "deploy", port: 22,
+        remoteDir: "", buildCommand: "", outputDir: ".",
+        expectedBranch: "", auth: "ssh", passwordEnv: "DEPLOY_SERVER_PASSWORD",
+        lockDirectory: false, lockBranch: false, lockMapping: false, checkGit: true
+    };
+}

package/dist/credentials.js

@@ -0,0 +1,24 @@
+import { AsyncEntry } from "@napi-rs/keyring";
+// 凭据绑定环境及服务器，编辑目标后不会误用旧服务器密码。
+function entry(profile) {
+    return new AsyncEntry("code-deploy", `${profile.id}:${profile.user}@${profile.host}:${profile.port}`);
+}
+export async function savePassword(profile, password) {
+    if (!password)
+        throw new Error("密码不能为空");
+    await entry(profile).setPassword(password);
+}
+export async function deletePassword(profile) {
+    await entry(profile).deletePassword();
+}
+// 密码仅传给 SSH 子进程，不写配置、命令行参数或日志。
+export async function resolvePassword(profile) {
+    if (profile.auth === "ssh")
+        return undefined;
+    const password = profile.auth === "env" ? process.env[profile.passwordEnv] : await entry(profile).getPassword();
+    if (!password)
+        throw new Error(profile.auth === "env"
+            ? `请设置环境变量 ${profile.passwordEnv}，或在环境设置中改用钥匙串密码`
+            : "钥匙串中没有此环境的密码，请在环境设置中保存");
+    return password;
+}

package/dist/deploy.js

@@ -0,0 +1,152 @@
+import { lstat, mkdtemp, readdir, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { profileSchema } from "./config.js";
+import { resolvePassword } from "./credentials.js";
+import { run, quote } from "./process.js";
+import { prepareRelease, inspectProject } from "./preflight.js";
+export const steps = ["发布前检查", "准备发布内容", "打包上传", "切换版本"];
+export { quote, run } from "./process.js";
+export { inspectProject } from "./preflight.js";
+// 使用 OpenSSH，沿用 ~/.ssh/config、known_hosts 及本机 SSH agent。
+async function withSsh(profile, task) {
+    const password = await resolvePassword(profile);
+    const temporary = await mkdtemp(path.join(tmpdir(), "code-deploy-ssh-"));
+    try {
+        const askpass = path.join(temporary, "askpass.sh");
+        if (password)
+            await writeFile(askpass, '#!/bin/sh\nprintf "%s\\n" "$CODE_DEPLOY_SSH_PASSWORD"\n', { mode: 0o700 });
+        const base = ["-o", "StrictHostKeyChecking=accept-new", "-o", "ConnectTimeout=10", "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=3", "-o", "NumberOfPasswordPrompts=1"];
+        if (!password)
+            base.push("-o", "BatchMode=yes");
+        return await task((command, args, options = {}) => run(command, [...base, command === "scp" ? "-P" : "-p", String(profile.port), ...args], {
+            ...options,
+            env: {
+                ...process.env,
+                ...(password ? { CODE_DEPLOY_SSH_PASSWORD: password, DISPLAY: process.env.DISPLAY || "code-deploy", SSH_ASKPASS: askpass, SSH_ASKPASS_REQUIRE: "force" } : {})
+            },
+            onOutput: text => options.onOutput?.(password ? text.split(password).join("[已隐藏]") : text)
+        }).then(result => password ? result.split(password).join("[已隐藏]") : result).catch(error => {
+            throw new Error(password ? String(error.message).split(password).join("[已隐藏]") : error.message);
+        }));
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+export async function checkServer(profile, signal) {
+    profileSchema.parse(profile);
+    return withSsh(profile, ssh => ssh("ssh", [`${profile.user}@${profile.host}`, `set -eu
+target=${quote(profile.remoteDir)}
+if [ -L "$target" ]; then echo '目标目录是符号链接，请选择真实目录' >&2; exit 1; fi
+if [ -d "$target" ]; then ls -ld "$target"; ls -1 "$target" | head -20; else echo '目标尚不存在，部署时会创建'; fi`], { signal }));
+}
+// version.json 用标记包裹传回，本地解析后美化展示。
+const versionBegin = "__CODE_DEPLOY_VERSION_BEGIN__";
+const versionEnd = "__CODE_DEPLOY_VERSION_END__";
+// 先完整解压，再保留旧版本并切换；失败时恢复旧目录。
+export function remoteDeployScript(profile, archive, token) {
+    const target = path.posix.normalize(profile.remoteDir).replace(/\/$/, "");
+    const parent = path.posix.dirname(target);
+    const name = path.posix.basename(target);
+    return `set -eu
+target=${quote(target)}
+parent=${quote(parent)}
+archive=${quote(archive)}
+stage=${quote(`${parent}/.${name}.stage-${token}`)}
+backup=${quote(`${parent}/.${name}.backup-${token}`)}
+lock=${quote(`${parent}/.${name}.code-deploy-lock`)}
+switched=0
+mkdir -p "$parent"
+if [ -L "$target" ]; then echo '目标目录是符号链接，已停止' >&2; exit 1; fi
+if [ -e "$target" ] && [ ! -d "$target" ]; then echo '目标不是目录，已停止' >&2; exit 1; fi
+if ! mkdir "$lock"; then echo '目标正在部署或留有锁目录，请核实后处理' >&2; exit 1; fi
+cleanup() {
+  status=$?
+  trap - EXIT HUP INT TERM
+  if [ "$switched" = 0 ] && [ -d "$backup" ] && [ ! -e "$target" ]; then mv "$backup" "$target"; fi
+  rm -rf -- "$stage"
+  rm -f -- "$archive"
+  rmdir "$lock"
+  exit "$status"
+}
+trap cleanup EXIT
+trap 'exit 130' HUP INT TERM
+mkdir "$stage"
+tar -xzf "$archive" -C "$stage"
+test -n "$(ls -A "$stage")"
+if [ -e "$target" ]; then mv "$target" "$backup"; fi
+mv "$stage" "$target"
+switched=1
+echo "部署完成: $target"
+if [ -d "$backup" ]; then echo "旧版本保留: $backup"; fi
+if [ -f "$target/version.json" ]; then echo '${versionBegin}'; cat "$target/version.json"; echo; echo '${versionEnd}'; fi`;
+}
+// 标记内的 JSON 解析为逐行键值；解析失败保留原文。
+export function formatRemoteOutput(text) {
+    const start = text.indexOf(versionBegin);
+    const stop = start < 0 ? -1 : text.indexOf(versionEnd, start);
+    if (start < 0 || stop < 0)
+        return text;
+    const body = text.slice(start + versionBegin.length, stop).trim();
+    let pretty = body;
+    try {
+        const data = JSON.parse(body);
+        if (data && typeof data === "object" && !Array.isArray(data)) {
+            pretty = ["version.json", ...Object.entries(data).map(([key, value]) => `  ${key}: ${value !== null && typeof value === "object" ? JSON.stringify(value) : String(value)}`)].join("\n");
+        }
+    }
+    catch { /* 保留原文 */ }
+    return `${text.slice(0, start)}${pretty}\n${text.slice(stop + versionEnd.length)}`;
+}
+export async function deploy(profile, emit, signal, confirm) {
+    const step = (index) => emit({ type: "step", index, text: steps[index] });
+    const log = (text) => emit({ type: "log", text });
+    step(0);
+    const project = await prepareRelease(profile, signal, confirm);
+    log(`${project.directory}\n${project.branch || "无分支"} · ${project.commit.slice(0, 10) || "无提交"}\n`);
+    // 构建前核验凭据，避免构建完成才发现没有密码。
+    await resolvePassword(profile);
+    step(1);
+    if (profile.buildCommand)
+        await run("/bin/sh", ["-c", profile.buildCommand], { cwd: project.directory, signal, onOutput: log });
+    else
+        log("未配置构建命令，直接发布现有目录内容\n");
+    const current = await inspectProject(profile, signal);
+    if (current.directory !== project.directory || current.branch !== project.branch || current.commit !== project.commit) {
+        throw new Error("准备期间源目录、分支或 HEAD 发生变化，请重新发起发布");
+    }
+    const output = await realpath(path.join(project.directory, profile.outputDir));
+    const relative = path.relative(project.directory, output);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        throw new Error("构建产物必须位于项目目录内");
+    if (!(await lstat(output)).isDirectory())
+        throw new Error("构建产物不是目录");
+    if (!(await readdir(output)).length)
+        throw new Error("发布目录为空");
+    // 禁止归档符号链接，避免服务器解压时逃离暂存目录。
+    const links = await run("find", [output, "-type", "l"], { signal });
+    if (links)
+        throw new Error(`构建产物包含符号链接，请先移除：\n${links}`);
+    const temporary = await mkdtemp(path.join(tmpdir(), "code-deploy-build-"));
+    const token = randomUUID();
+    const localArchive = path.join(temporary, "dist.tar.gz");
+    const remoteArchive = `/tmp/code-deploy-${token}.tar.gz`;
+    try {
+        step(2);
+        await run("tar", [...(process.platform === "darwin" ? ["--no-xattrs"] : []), "-czf", localArchive, "-C", output, "."], {
+            signal, env: { ...process.env, COPYFILE_DISABLE: "1" }
+        });
+        await withSsh(profile, async (ssh) => {
+            await ssh("scp", [localArchive, `${profile.user}@${profile.host.includes(":") ? `[${profile.host}]` : profile.host}:${remoteArchive}`], { signal, onOutput: log });
+            step(3);
+            let remoteOutput = "";
+            await ssh("ssh", [`${profile.user}@${profile.host}`, remoteDeployScript(profile, remoteArchive, token)], { signal, onOutput: text => { remoteOutput += text; } });
+            log(formatRemoteOutput(remoteOutput));
+        });
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}

package/dist/preflight.js

@@ -0,0 +1,129 @@
+import { realpath, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { profileSchema, targetKey } from "./config.js";
+import { run } from "./process.js";
+// 当前目录就是实际源目录；目录锁不会偷偷切换到另一个工作区。
+export async function inspectProject(profile, signal, refresh = false, cwd = process.cwd()) {
+    profileSchema.parse(profile);
+    const directory = await realpath(cwd);
+    if (!(await stat(directory)).isDirectory())
+        throw new Error("源目录不是目录");
+    if (profile.lockDirectory || profile.lockMapping) {
+        const expected = await realpath(profile.projectDir);
+        if (directory !== expected)
+            throw new Error(`本地目录已锁定，请在 ${expected} 运行；当前 ${directory}`);
+    }
+    const state = { directory, branch: "", commit: "", changes: "", upstream: "", ahead: 0, behind: 0, warnings: [], fingerprint: "" };
+    const git = (args) => run("git", args, { cwd: directory, signal, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+    let isGit = false;
+    try {
+        isGit = await git(["rev-parse", "--is-inside-work-tree"]) === "true";
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+    }
+    if (!isGit) {
+        if (profile.lockBranch || profile.lockMapping)
+            throw new Error("分支锁或映射锁要求源目录属于 Git 工作区");
+        if (profile.checkGit)
+            state.warnings.push("源目录不属于 Git 工作区，无法检查分支状态");
+        return finish(state);
+    }
+    state.branch = await git(["branch", "--show-current"]);
+    state.commit = await git(["rev-parse", "HEAD"]).catch(error => {
+        if (signal?.aborted)
+            throw error;
+        return "";
+    });
+    enforceLocks(profile, state);
+    state.changes = await git(["status", "--porcelain=v1", "--untracked-files=all"]);
+    if (!profile.checkGit)
+        return finish(state);
+    if (state.changes)
+        state.warnings.push(`存在未提交改动（含暂存、未暂存或未跟踪文件）：\n${state.changes}`);
+    if (!state.branch)
+        state.warnings.push("当前处于 detached HEAD，未检出命名分支");
+    try {
+        state.upstream = await git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        state.warnings.push("当前分支没有可用的上游跟踪分支，无法确认是否有未拉取提交");
+        return finish(state);
+    }
+    if (refresh) {
+        try {
+            const remote = await git(["config", "--get", `branch.${state.branch}.remote`]);
+            if (remote && remote !== ".")
+                await git(["fetch", "--no-tags", "--", remote]);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            state.warnings.push(`刷新远程分支失败，未拉取状态可能过期：\n${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const [ahead, behind] = (await git(["rev-list", "--left-right", "--count", "HEAD...@{upstream}"])).split(/\s+/).map(Number);
+    state.ahead = ahead;
+    state.behind = behind;
+    if (state.behind)
+        state.warnings.push(`当前分支落后 ${state.upstream} ${state.behind} 个提交，存在未拉取代码`);
+    if (state.ahead)
+        state.warnings.push(`当前分支领先 ${state.upstream} ${state.ahead} 个提交，存在未推送代码`);
+    return finish(state);
+}
+// 锁定规则属于硬约束，确认 Git 警告不能绕过。
+function enforceLocks(profile, state) {
+    if (profile.lockBranch && (!profile.expectedBranch || state.branch !== profile.expectedBranch)) {
+        throw new Error(`分支不匹配：要求 ${profile.expectedBranch || "（未配置）"}，当前 ${state.branch || "detached HEAD"}`);
+    }
+    if (!profile.lockMapping)
+        return;
+    const mapping = profile.mapping;
+    if (!mapping || state.directory !== mapping.projectDir || targetKey(profile) !== targetKey(mapping)) {
+        throw new Error("锁定映射不匹配：本地目录、服务器及远程目录必须与保存的映射完全对应；请先解除映射锁再修改");
+    }
+}
+// 指纹用于确认后复核，目录、提交或警告发生变化时重新等待确认。
+function finish(state) {
+    state.fingerprint = createHash("sha256").update(JSON.stringify({
+        directory: state.directory, branch: state.branch, commit: state.commit,
+        changes: state.changes, upstream: state.upstream, ahead: state.ahead, behind: state.behind
+    })).digest("hex");
+    return state;
+}
+export async function captureMapping(profile, signal) {
+    // 配置阶段只抓取现状，分支锁、映射锁的判定留到发布时。
+    const state = await inspectProject({ ...profile, lockMapping: false, lockDirectory: true, lockBranch: false, checkGit: false }, signal);
+    if (!state.branch)
+        throw new Error("请先检出要锁定的发布分支");
+    return { ...profile, projectDir: state.directory, lockMapping: true, mapping: {
+            projectDir: state.directory, branch: state.branch, host: profile.host, user: profile.user,
+            port: profile.port, remoteDir: profile.remoteDir
+        } };
+}
+export class GitConfirmationRequired extends Error {
+    state;
+    constructor(state) {
+        super(`Git 状态需要确认：\n${state.warnings.join("\n\n")}`);
+        this.state = state;
+        this.name = "GitConfirmationRequired";
+    }
+}
+// TUI 和命令行共用确认入口，默认拒绝无交互的异常状态发布。
+export async function prepareRelease(profile, signal, confirm) {
+    let state = await inspectProject(profile, signal, profile.checkGit);
+    while (state.warnings.length) {
+        if (!confirm)
+            throw new GitConfirmationRequired(state);
+        if (!await confirm(state))
+            throw new Error("已取消发布");
+        const current = await inspectProject(profile, signal, false);
+        if (current.fingerprint === state.fingerprint)
+            return current;
+        state = await inspectProject(profile, signal, profile.checkGit);
+    }
+    return state;
+}

package/dist/process.js

@@ -0,0 +1,53 @@
+import { spawn } from "node:child_process";
+import { stripVTControlCharacters } from "node:util";
+// 参数以数组传递，只有用户明确配置的构建命令通过 shell 执行。
+export function run(command, args, options = {}) {
+    if (options.signal?.aborted)
+        return Promise.reject(new Error("操作已取消"));
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"],
+            detached: process.platform !== "win32"
+        });
+        let output = "";
+        let killTimer;
+        function kill(signal) {
+            try {
+                if (process.platform !== "win32" && child.pid)
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch (error) {
+                if (error.code !== "ESRCH")
+                    throw error;
+            }
+        }
+        const abort = () => {
+            kill("SIGTERM");
+            killTimer = setTimeout(() => kill("SIGKILL"), 3000);
+            killTimer.unref();
+        };
+        const collect = (chunk) => {
+            const text = stripVTControlCharacters(chunk).replace(/\r/g, "");
+            output = (output + text).slice(-100_000);
+            options.onOutput?.(text);
+        };
+        child.stdout.setEncoding("utf8").on("data", collect);
+        child.stderr.setEncoding("utf8").on("data", collect);
+        options.signal?.addEventListener("abort", abort, { once: true });
+        child.on("error", reject);
+        child.on("close", (code, signal) => {
+            clearTimeout(killTimer);
+            options.signal?.removeEventListener("abort", abort);
+            if (options.signal?.aborted)
+                reject(new Error("操作已取消；若已进入远程切换阶段，请检查服务器上的当前版本"));
+            else if (code !== 0)
+                reject(new Error(`${command} 执行失败 (${signal || code})\n${output.slice(-4000)}`));
+            else
+                resolve(output.trim());
+        });
+    });
+}
+// 单引号转义用于远程 POSIX shell，支持目录中的空格及引号。
+export const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;

package/dist/settings.js

@@ -0,0 +1,184 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useState } from "react";
+import { Box, Text, useInput } from "ink";
+import { PasswordInput, TextInput } from "@inkjs/ui";
+import { homedir } from "node:os";
+import { newProfile, profileSchema } from "./config.js";
+import { savePassword } from "./credentials.js";
+import { captureMapping } from "./preflight.js";
+export const colors = { accent: "#A78BFA", warm: "#E8BC73", muted: "#7C8499", good: "#8DC7A5", error: "#E88E8E" };
+export const authNames = { env: "环境变量", keychain: "系统钥匙串", ssh: "SSH 密钥 / Agent" };
+// 向导按此顺序逐项提问；已答项留在上方可回看。
+const fields = [
+    { key: "id", label: "环境标识", hint: "小写字母、数字、连字符；创建后固定" },
+    { key: "name", label: "显示名称", hint: "为这条发布配置取一个名称" },
+    { key: "projectDir", label: "本地目录 A", hint: "目录锁或映射锁开启时必须在此目录运行；未锁定时使用启动目录" },
+    { key: "host", label: "目标服务器", hint: "IP、域名或 SSH 别名" },
+    { key: "user", label: "登录账号", hint: "服务器上的 SSH 登录账号" },
+    { key: "port", label: "SSH 端口", hint: "服务器的 SSH 端口" },
+    { key: "remoteDir", label: "远程目录 B", hint: "发布时整体替换此目录，旧内容保留为同级备份" },
+    { key: "buildCommand", label: "构建命令", hint: "在源目录执行；留空表示直接发布已有内容" },
+    { key: "outputDir", label: "发布内容", hint: "源目录内的相对路径；. 表示整个源目录，dist 表示构建产物" },
+    { key: "expectedBranch", label: "指定分支", hint: "开启分支锁时必须填写；关闭时仅保存此值，不限制发布" },
+    { key: "lockDirectory", label: "锁定本地目录", hint: "开启后只能在本地目录 A 本身运行；子目录也不允许" },
+    { key: "lockBranch", label: "锁定发布分支", hint: "发布时检查实际分支等于指定分支，用错分支时拦截提醒" },
+    { key: "lockMapping", label: "锁定映射关系", hint: "记录目录 A 与服务器、目录 B 的对应关系；分支由分支锁单独约束；需在目录 A 开启" },
+    { key: "checkGit", label: "Git 状态检查", hint: "默认开启；刷新上游，检查未提交、未拉取及未推送代码，异常时等待确认" },
+    { key: "auth", label: "登录方式", hint: "支持 SSH 密钥、环境变量或系统钥匙串" },
+    { key: "passwordEnv", label: "密码环境变量", hint: "仅环境变量认证使用；这里填写变量名，不是密码" }
+];
+const actions = ["保存配置", "保存钥匙串密码", "取消修改"];
+const protectedFields = ["projectDir", "host", "user", "port", "remoteDir", "expectedBranch"];
+const message = (error) => error instanceof Error ? error.message : String(error);
+export function fieldValue(profile, key) {
+    if (typeof profile[key] === "boolean")
+        return profile[key] ? "开启" : "关闭";
+    if (key === "auth")
+        return authNames[profile.auth];
+    return String(profile[key] || "（未设置）");
+}
+// 引导式向导：一次只问当前一项，已答项保留在上方；↑↓ 回看或跳过。
+export function Settings({ config, profile, initial, onSave, onCancel }) {
+    const [draft, setDraft] = useState(initial || profile || newProfile);
+    const [step, setStep] = useState(0);
+    const [choice, setChoice] = useState(0);
+    const [enteringPassword, setEnteringPassword] = useState(false);
+    const [error, setError] = useState("");
+    const [busy, setBusy] = useState(false);
+    const field = fields[step];
+    const done = step >= fields.length;
+    const fixed = field?.key === "id" && Boolean(profile);
+    const locked = Boolean(field && draft.lockMapping && protectedFields.includes(field.key));
+    const isBoolean = field ? typeof draft[field.key] === "boolean" : false;
+    async function attempt(task) {
+        if (busy)
+            return;
+        setBusy(true);
+        setError("");
+        try {
+            await task();
+        }
+        catch (failure) {
+            setError(message(failure));
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    async function save() {
+        if (!profile && config.profiles.some(item => item.id === draft.id))
+            throw new Error("环境标识已存在");
+        profileSchema.parse(draft);
+        if (draft.lockBranch && !draft.expectedBranch)
+            throw new Error("开启分支锁时必须填写指定分支");
+        await onSave(draft);
+    }
+    function advance() { setError(""); setStep(current => Math.min(fields.length, current + 1)); }
+    function submitText(raw) {
+        if (!field)
+            return;
+        let value = field.key === "port" ? Number(raw) : raw.trim();
+        if (field.key === "projectDir" && typeof value === "string" && value.startsWith("~/"))
+            value = `${homedir()}/${value.slice(2)}`;
+        const result = profileSchema.shape[field.key].safeParse(value);
+        if (!result.success) {
+            setError(result.error.issues[0].message);
+            return;
+        }
+        setDraft({ ...draft, [field.key]: result.data });
+        advance();
+    }
+    function toggleBoolean() {
+        if (!field)
+            return;
+        const value = draft[field.key];
+        if (field.key === "lockMapping" && !value)
+            void attempt(async () => { setDraft(await captureMapping(profileSchema.parse(draft))); });
+        else
+            setDraft({ ...draft, [field.key]: !value });
+    }
+    function cycleAuth(direction) {
+        const order = Object.keys(authNames);
+        setDraft({ ...draft, auth: order[(order.indexOf(draft.auth) + direction + order.length) % order.length] });
+    }
+    useInput((input, key) => {
+        if (key.ctrl && input === "s") {
+            void attempt(save);
+            return;
+        }
+        if (busy)
+            return;
+        if (key.escape) {
+            if (enteringPassword) {
+                setEnteringPassword(false);
+                setError("");
+            }
+            else
+                onCancel();
+            return;
+        }
+        if (enteringPassword)
+            return;
+        if (done) {
+            if (key.leftArrow)
+                setChoice((choice + actions.length - 1) % actions.length);
+            if (key.rightArrow)
+                setChoice((choice + 1) % actions.length);
+            if (key.upArrow)
+                setStep(fields.length - 1);
+            if (!key.return)
+                return;
+            setError("");
+            if (choice === 0)
+                void attempt(save);
+            else if (choice === 1)
+                setEnteringPassword(true);
+            else
+                onCancel();
+            return;
+        }
+        if (!field)
+            return;
+        if (key.upArrow) {
+            setError("");
+            setStep(Math.max(0, step - 1));
+            return;
+        }
+        if (key.downArrow) {
+            advance();
+            return;
+        }
+        if (fixed || locked) {
+            if (key.return)
+                advance();
+            return;
+        }
+        if (isBoolean) {
+            if (input === " " || key.leftArrow || key.rightArrow)
+                toggleBoolean();
+            if (key.return)
+                advance();
+            return;
+        }
+        if (field.key === "auth") {
+            if (key.leftArrow)
+                cycleAuth(-1);
+            if (key.rightArrow || input === " ")
+                cycleAuth(1);
+            if (key.return)
+                advance();
+            return;
+        }
+        // 文本字段的 Enter 由 TextInput 的 onSubmit 处理
+    });
+    return _jsxs(Box, { flexDirection: "column", flexGrow: 1, children: [_jsxs(Text, { bold: true, color: colors.warm, children: [profile ? "编辑配置" : "新建配置", " ", _jsxs(Text, { color: colors.muted, children: ["\u00B7 ", Math.min(step + 1, fields.length), "/", fields.length, " \u00B7 \u5DF2\u7B54\u9879\u4FDD\u7559\u5728\u4E0A\u65B9"] })] }), _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [fields.slice(0, step).map(item => _jsxs(Box, { children: [_jsx(Box, { width: 16, flexShrink: 0, children: _jsx(Text, { color: colors.muted, wrap: "truncate", children: item.label }) }), _jsx(Box, { flexGrow: 1, minWidth: 0, children: _jsx(Text, { wrap: "truncate", color: typeof draft[item.key] === "boolean" ? (draft[item.key] ? colors.good : colors.muted) : (!draft[item.key] ? colors.muted : undefined), children: fieldValue(draft, item.key) }) })] }, item.key)), !done && field && _jsxs(Box, { flexDirection: "column", marginTop: step > 0 ? 1 : 0, children: [_jsxs(Box, { children: [_jsx(Box, { width: 16, flexShrink: 0, children: _jsxs(Text, { bold: true, color: colors.accent, wrap: "truncate", children: ["\u203A ", field.label] }) }), _jsx(Box, { flexGrow: 1, minWidth: 0, children: isBoolean || field.key === "auth"
+                                            ? _jsxs(Text, { color: isBoolean && !draft[field.key] ? colors.muted : colors.accent, children: [fieldValue(draft, field.key), " ", _jsx(Text, { color: colors.muted, children: "\uFF08\u2190\u2192 \u5207\u6362\uFF09" })] })
+                                            : fixed || locked
+                                                ? _jsxs(Text, { wrap: "truncate", children: [fieldValue(draft, field.key), " ", _jsxs(Text, { color: colors.muted, children: ["\uFF08", fixed ? "创建后固定" : "映射锁已锁定", "\uFF09"] })] })
+                                                : _jsx(TextInput, { defaultValue: String(draft[field.key] || ""), onSubmit: submitText }, `${field.key}-${step}`) })] }), _jsxs(Text, { color: colors.muted, wrap: "truncate", children: ["  ", field.hint] })] }), done && _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Box, { gap: 2, children: actions.map((label, offset) => _jsxs(Text, { bold: offset === choice, color: offset === choice ? colors.accent : colors.muted, children: [offset === choice ? "› " : "  ", label] }, label)) }), _jsx(Text, { color: colors.muted, children: "\u2190\u2192 \u9009\u62E9 \u00B7 Enter \u786E\u8BA4 \u00B7 \u2191 \u8FD4\u56DE\u4FEE\u6539" }), enteringPassword && _jsx(PasswordInput, { onSubmit: password => void attempt(async () => {
+                                    const parsed = profileSchema.parse(draft);
+                                    await savePassword(parsed, password);
+                                    setDraft({ ...parsed, auth: "keychain" });
+                                    setEnteringPassword(false);
+                                }) })] }), draft.lockMapping && draft.mapping && _jsxs(Text, { color: colors.warm, wrap: "truncate", children: ["\u9501\u5B9A\u6620\u5C04\uFF1A", draft.mapping.projectDir, " \u2192 ", draft.mapping.host, ":", draft.mapping.remoteDir, "\uFF08\u5206\u652F\u7531\u5206\u652F\u9501\u5355\u72EC\u7EA6\u675F\uFF09"] }), error && _jsx(Text, { color: colors.error, wrap: "truncate", children: error })] }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: _jsx(Text, { color: colors.muted, wrap: "truncate", children: busy ? "正在处理…" : "Enter 确认 · ↑↓ 上一项 / 跳过 · Ctrl+S 保存 · Esc 取消" }) })] });
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@akairos/code-deploy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "Configurable local-to-SSH directory publishing with an Ink terminal interface",
+  "type": "module",
+  "bin": { "code-deploy": "dist/cli.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "tsc",
+    "dev": "tsx src/cli.tsx",
+    "start": "node dist/cli.js",
+    "test": "tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@inkjs/ui": "^2.0.0",
+    "@napi-rs/keyring": "^2.1.1",
+    "ink": "^8.0.0",
+    "react": "^19.2.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.0",
+    "ink-testing-library": "^4.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  }
+}