@syrkos/filaxis 0.1.0-alpha.10

package/src/shell-discovery.ts

@@ -0,0 +1,52 @@
+/**
+ * shell-discovery.ts — 本地 shell 发现（Windows WSL 入口坑防护——Gemini 试用反馈 #1）
+ *
+ * 痛点：win32 PATH 上的 `bash` 可能是 `C:\Windows\System32\bash.exe`（WSL 转发入口，
+ * 未配置默认分发时 spawn 即挂）。发现序：
+ *   1. 显式传入（opts.shell / FILAXIS_SHELL 环境变量）
+ *   2. PATH 上的 bash——**若非 System32 WSL 入口则直接用**（并发 spawn 热路径：
+ *      完整路径 exe 在 Windows Defender 并发扫描下首启可达 20s+，PATH 名 spawn 无此坑——生产实证）
+ *   3. Git Bash 标准路径嗅探（PATH bash 即 WSL 入口的兜底）
+ *   4. 回退 "bash" + 诊断提示（用户可能真有 WSL 发行版）
+ */
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+
+const GIT_BASH_CANDIDATES = [
+    "C:\\Program Files\\Git\\bin\\bash.exe",
+    "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
+    "C:\\Program Files (x86)\\Git\\bin\\bash.exe",
+];
+
+/** PATH 上 bash 的解析结果（无则 undefined） */
+function bashOnPath(): string | undefined {
+    try {
+        return execSync("where bash", { stdio: ["ignore", "pipe", "ignore"] })
+            .toString().split("\n").map((l) => l.trim()).filter(Boolean)[0];
+    } catch {
+        return undefined;
+    }
+}
+
+/** 发现本执行 shell（Linux/macOS 恒 "bash"） */
+export function resolveLocalShell(preferred?: string, log?: { warn(msg: string): void }): string {
+    if (preferred) return preferred;
+    if (process.platform !== "win32") return "bash";
+
+    const fromEnv = process.env.FILAXIS_SHELL;
+    if (fromEnv) return fromEnv;
+
+    const p = bashOnPath();
+    if (p && !/System32/i.test(p)) return "bash"; // PATH 上的真 bash（Git Bash 等）——并发热路径
+
+    for (const c of GIT_BASH_CANDIDATES) {
+        if (existsSync(c)) return c;
+    }
+
+    log?.warn(
+        "[Filaxis] Windows 未找到可用 bash（PATH " +
+        (p ? "上是 WSL 转发入口" : "上无 bash") +
+        "且未嗅探到 Git Bash）——请安装 Git（https://git-scm.com）或设 FILAXIS_SHELL 指向 bash.exe 完整路径",
+    );
+    return "bash";
+}

package/src/ssh-helpers.ts

@@ -0,0 +1,225 @@
+/**
+ * ssh-helpers.ts — SSH 连接参数渲染/进入管线/层状态机/层选择（纯函数）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/ssh-pty-driver.ts` 纯函数段
+ * （源锚 8977ff3），OSS 化：剥 Aethelum 概念，marker 前缀换 Filaxis 命名空间。
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { RuntimeDescriptor } from "./driver.js";
+
+/** 端口透传（随层连接生命周期——层在隧道在，层断即撤） */
+export interface SshPortForward {
+    kind: "L" | "R" | "D";
+    port: number;
+    target?: string;
+    bind?: string;
+}
+
+export function renderForwardArg(f: SshPortForward): string {
+    if (f.kind === "D") return String(f.port);
+    return `${f.bind ? `${f.bind}:` : ""}${f.port}:${f.target ?? ""}`;
+}
+
+/** SSH 连接参数（结构化——渲染进 ssh 命令行与身份解析） */
+export interface SshConnParams {
+    user?: string;
+    port?: number;
+    keyFile?: string;
+    /** 跳板（-J；途径机不占栈层，由 ssh 自身代理） */
+    jump?: string;
+    forwards?: SshPortForward[];
+    /**
+     * 主机密钥策略（FEAT-12 / AC-12）：
+     * - "tofu"（缺省）——accept-new：首连自动收主机键，已知主机不匹配则拒绝
+     * - "strict"——StrictHostKeyChecking=yes：仅已知主机可连（配合 knownHostsFile 自定义信任锚）
+     */
+    hostKeyPolicy?: "tofu" | "strict";
+    /** 自定义 known_hosts 路径（UserKnownHostsFile；strict 模式的信任锚，缺省用户默认） */
+    knownHostsFile?: string;
+}
+
+export type SshHop = string | { host: string; conn?: SshConnParams };
+
+const isHopObj = (h: SshHop): h is { host: string; conn?: SshConnParams } => typeof h === "object";
+
+export function hopHost(hop: SshHop): string {
+    return isHopObj(hop) ? hop.host : hop;
+}
+
+/** 人读形式：root@10.0.20.1:2222 -J jump -L8080→localhost:80 */
+export function hopLabel(hop: SshHop): string {
+    if (!isHopObj(hop) || !hop.conn) return hopHost(hop);
+    const { user, port, jump, forwards } = hop.conn;
+    let s = `${user ? `${user}@` : ""}${hopHost(hop)}${port ? `:${port}` : ""}`;
+    if (jump) s += ` -J ${jump}`;
+    if (forwards?.length) {
+        s += ` ${forwards.map((f) => (f.kind === "D" ? `-D${f.port}` : `-${f.kind}${f.port}→${f.target}`)).join(" ")}`;
+    }
+    return s;
+}
+
+/** ssh 命令行参数（spawn 数组与 ssh -G 解析共用） */
+export function sshArgsFor(hop: SshHop): string[] {
+    if (!isHopObj(hop) || !hop.conn) return [hopHost(hop)];
+    const { user, port, keyFile, jump, forwards } = hop.conn;
+    const args: string[] = [];
+    if (jump) args.push("-J", jump);
+    if (keyFile) args.push("-i", expandHomePath(keyFile));
+    if (port) args.push("-p", String(port));
+    for (const f of forwards ?? []) {
+        args.push(f.kind === "L" ? "-L" : f.kind === "R" ? "-R" : "-D", renderForwardArg(f));
+    }
+    args.push(user ? `${user}@${hopHost(hop)}` : hopHost(hop));
+    return args;
+}
+
+/** PTY 内单行发送所需的引用形式（私钥路径含空格等场景） */
+export function sshArgsQuoted(hop: SshHop): string {
+    return sshArgsFor(hop)
+        .map((a) => (/^[A-Za-z0-9_@:./-]+$/.test(a) ? a : `"${a.replace(/"/g, '\\"')}"`))
+        .join(" ");
+}
+
+/** `~` 展开——spawn 参数数组不经过 shell，tilde 不会被展开（生产实证：公钥认证被拒 exit 255） */
+export function expandHomePath(p: string): string {
+    if (p === "~") return homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\")) return join(homedir(), p.slice(2));
+    return p;
+}
+
+/** 进入管线一步：建层时在链路末端落进内层 shell 的一条命令（docker exec / kubectl exec / su 等） */
+export interface EnterStep {
+    /** 进入命令原文（重放用） */
+    cmd: string;
+    /** 显示/层选择标签（缺省截取 cmd） */
+    label?: string;
+}
+
+/** 层的完整进入管线（归一化读取）：config.enterPipeline 为准；legacy enterCmd/enterLabel 就地归一 */
+export function enterStepsOf(config: Record<string, unknown> | undefined): EnterStep[] {
+    if (Array.isArray(config?.enterPipeline)) {
+        return (config.enterPipeline as unknown[])
+            .filter((s) => s && typeof (s as EnterStep).cmd === "string" && (s as EnterStep).cmd)
+            .map((s) => ({ cmd: String((s as EnterStep).cmd), label: (s as EnterStep).label ? String((s as EnterStep).label) : undefined }));
+    }
+    const legacy = config?.enterCmd ? String(config.enterCmd) : "";
+    return legacy ? [{ cmd: legacy, label: config?.enterLabel ? String(config.enterLabel) : undefined }] : [];
+}
+
+/**
+ * 自治建链选项（AC-12：host key 策略显式可配）：
+ * - ConnectTimeout=10（先于握手超时暴露真相）；ServerAlive 30×3（静默死亡 ~90s 内暴露）
+ * - hostKeyPolicy：tofu（缺省，accept-new）/ strict（yes + 可选 UserKnownHostsFile）
+ * 不加 BatchMode：禁交互提示会抹掉「等待输入」这个可感知状态——感知到 prompt 后
+ * 把原文直交调用方，而不是假装它不存在。
+ * 渲染只含密钥/known_hosts **路径**，永不包含其内容（AC-12 无泄漏红线）。
+ */
+export function autonomousSshOpts(conn?: SshConnParams): string[] {
+    const opts = ["-o", "ConnectTimeout=10", "-o", "ServerAliveInterval=30", "-o", "ServerAliveCountMax=3"];
+    if (conn?.hostKeyPolicy === "strict") {
+        opts.push("-o", "StrictHostKeyChecking=yes");
+        if (conn.knownHostsFile) {
+            opts.push("-o", `UserKnownHostsFile=${expandHomePath(conn.knownHostsFile)}`);
+        }
+    } else {
+        opts.push("-o", "StrictHostKeyChecking=accept-new"); // TOFU 缺省
+    }
+    return opts;
+}
+
+/** root 层 spawn 全参数（含 -tt 强制 PTY） */
+export function rootSshSpawnArgs(destArgs: string[], conn?: SshConnParams): string[] {
+    return ["-tt", ...autonomousSshOpts(conn), ...destArgs];
+}
+
+/** PTY 内 hop 登录命令（选项语义与 root 对齐） */
+export function hopSshCommand(hop: SshHop): string {
+    const conn = typeof hop === "object" ? hop.conn : undefined;
+    return `ssh ${autonomousSshOpts(conn).join(" ")} ${sshArgsQuoted(hop)}`;
+}
+
+/** 「等待输入」感知特征：ssh 停在交互提示（密码/口令/yes-no）——检测到即失败交还原文 */
+export const SSH_INPUT_WAIT_RE =
+    /(?:password|passphrase|verification\s+code|login|密码|口令)[^\n]*[:：]\s*$|yes\s*\/\s*no|are you sure|continue connecting/i;
+
+const identityCache = new Map<string, string>();
+/** 连接身份解析（ssh -G 本地解析不连网）；失败回退 unresolved: 前缀（视为不相同，不误拦） */
+export async function resolveSshIdentity(hop: SshHop): Promise<string> {
+    const cacheKey = typeof hop === "string" ? hop : JSON.stringify(hop);
+    const cached = identityCache.get(cacheKey);
+    if (cached) return cached;
+    try {
+        const { execFile } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const X = promisify(execFile);
+        const { stdout } = await X("ssh", ["-G", ...sshArgsFor(hop)], { timeout: 8000 });
+        const h = stdout.match(/^hostname (\S+)$/m)?.[1] ?? hopHost(hop);
+        const p = stdout.match(/^port (\d+)$/m)?.[1] ?? "22";
+        const u = stdout.match(/^user (\S+)$/m)?.[1] ?? "";
+        const id = `${u ? u + "@" : ""}${h}:${p}`;
+        identityCache.set(cacheKey, id);
+        return id;
+    } catch {
+        return `unresolved:${hopHost(hop)}`;
+    }
+}
+
+/** 层的完整途经身份链（target + hops），供回环检测 */
+export function layerPathIdentities(desc: RuntimeDescriptor): SshHop[] {
+    const hops: SshHop[] = Array.isArray(desc.config?.sshHops) ? (desc.config.sshHops as SshHop[]) : [];
+    const connParams = desc.config?.connParams as SshConnParams | undefined;
+    const root: SshHop = desc.target ? (connParams ? { host: desc.target, conn: connParams } : desc.target) : "";
+    return [root, ...hops].filter(Boolean);
+}
+
+/** 层显示名（root 含端口/用户 + 途经链 + 进入标签） */
+export function layerDisplayName(desc: RuntimeDescriptor): string {
+    const hops = (Array.isArray(desc.config?.sshHops) ? (desc.config.sshHops as SshHop[]) : []).map((h) => hopLabel(h));
+    const connParams = desc.config?.connParams as SshConnParams | undefined;
+    const root = hopLabel(connParams ? { host: desc.target ?? "?", conn: connParams } : desc.target ?? "?");
+    const parts = [root, ...hops];
+    parts.push(...enterStepsOf(desc.config as Record<string, unknown> | undefined).map((s) => s.label ?? s.cmd.slice(0, 24)));
+    return parts.join(" → ");
+}
+
+/** 层显示标签（descriptor 链 + 容器短 ID 后缀） */
+export function layerDisplayLabel(d: { descriptor: RuntimeDescriptor; containerId?: string }): string {
+    const base = layerDisplayName(d.descriptor);
+    return d.containerId ? `${base}(${d.containerId})` : base;
+}
+
+/**
+ * exec 通道（非 PTY）进入管线重放渲染（FEAT-03 层上下文拼装）：
+ * 每步清洗 -it → -i（非交互）后要求以 shell 结尾（docker exec -it ctr bash 形态）——
+ * 渲染为 stdin 管道链：`… bash -s` 逐层读 stdin，命令文本从本地注入，零嵌套引用。
+ * 任一步非 shell 结尾形态（如裸 su -）→ 不可直达层（exec 通道拒绝，用 pty 通道）。
+ */
+const SHELL_TAIL_RE = /(?:^|\s)(bash|sh|zsh|ash|dash)\s*$/;
+
+export type ExecChannelRender =
+    | { kind: "ok"; remoteArgs: string[]; stdinCmd: string }
+    | { kind: "unreachable"; reason: string; step: string };
+
+export function renderExecChannel(
+    steps: EnterStep[],
+    command: string,
+    opts: { cwd?: string; marker: string; nonceWrapped: string },
+): ExecChannelRender {
+    const remoteArgs: string[] = [];
+    for (const s of steps) {
+        // -it / -t → -i（非交互）；进入命令须以 shell 结尾（内层读 stdin）
+        const cleaned = s.cmd.replace(/(^|\s)-(it|ti)\b/g, "$1-i").replace(/(^|\s)-t\b/g, "$1-i").trim();
+        const m = SHELL_TAIL_RE.exec(cleaned);
+        if (!m) {
+            return { kind: "unreachable", reason: "进入命令非「… shell」形态（无法非交互重放）", step: s.cmd };
+        }
+        remoteArgs.push(...cleaned.split(/\s+/), "-s"); // shell -s：从 stdin 读命令
+    }
+    // 终层远端 shell：POSIX sh 通吃（包装脚本纯 POSIX——报告 #3：FreeBSD/Alpine 无 bash
+    // 也能跑；bash 系统上 sh 通常为 bash/ash 链接，行为兼容）
+    remoteArgs.push("sh", "-s");
+    const cd = opts.cwd ? `cd ${JSON.stringify(opts.cwd)} 2>/dev/null || true; ` : "";
+    void command;
+    return { kind: "ok", remoteArgs, stdinCmd: `${cd}${opts.nonceWrapped}` };
+}