tmuxes 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tmuxes contributors
+
+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,213 @@
+<div align="center">
+
+# 🖥️ tmuxes
+
+**简体中文** ｜ [English](./README.en.md)
+
+### 一个浏览器标签页，掌控一整群 CLI coding agent。
+
+**Claude Code · Codex · OpenCode · Hermes** —— 每个 agent 独占一个 tmux 会话，
+横跨 **本地 · SSH · WSL**，还自带每个 agent 工作目录的文件浏览器。
+
+<p>
+<img alt="platform" src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows%2011-2b2b2b?style=flat-square">
+<img alt="React" src="https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=black">
+<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square&logo=typescript&logoColor=white">
+<img alt="Node.js" src="https://img.shields.io/badge/Node.js-22-339933?style=flat-square&logo=nodedotjs&logoColor=white">
+<img alt="Vite" src="https://img.shields.io/badge/Vite-8-646CFF?style=flat-square&logo=vite&logoColor=white">
+<img alt="tmux" src="https://img.shields.io/badge/tmux-3.x-1BB91F?style=flat-square&logo=tmux&logoColor=white">
+<img alt="xterm.js" src="https://img.shields.io/badge/xterm.js-6-1f6feb?style=flat-square">
+</p>
+
+<sub>🔒 仅本机 · ⚡ 一键启动 · 🪟 Windows 上直通 WSL · 🧩 零配置</sub>
+
+</div>
+
+---
+
+> **为什么做这个？** 现代编码 agent 都是常驻的终端进程。同时跑好几个，你就开始在一堆窗格、SSH 窗口之间手忙脚乱：
+> 「等等，刚那个是在哪台机器上来着？」**tmuxes** 把它们全塞进一个清爽的网页 UI：
+> 开一个会话、丢进文件夹、看它干活、顺手瞄一眼它正在改的文件 —— 本地还是远程，都是同一个视图。
+
+## ✨ 特性亮点
+
+| | |
+|---|---|
+| 🧠 **为 agent 而生** | 每个 agent 独占一个 tmux 会话。新建时可带初始命令（比如 `claude` 或 `codex`），选中后右侧就是一个**完全可交互的实时终端**。 |
+| 🌐 **本地 · SSH · WSL · 原生 Windows** | 一个侧边栏同时列出你的本机、`~/.ssh/config` 里的主机、（Windows 上）你的 WSL 发行版，以及（Windows）原生 PowerShell / cmd 会话 —— 全部并排排开。 |
+| 🗂️ **文件夹树** | 像资源管理器一样，把会话拖进**可拖拽的文件夹**里整理。按目标分别持久化到本地。 |
+| 📂 **实时文件浏览 + 编辑** | 侧边栏底部跟随每个会话的**工作目录** —— 点一个代码文件就能把终端一分为二，在下面**直接读和改**（可保存、撤销/重做）。 |
+| 🔁 **真·多端同步** | 基于原生 `tmux attach`：同一个会话开两个标签页，逐键同步、互为镜像。 |
+| ⚙️ **可调** | 侧边栏、终端、文件查看器的字号都能调，**实时生效**、刷新后仍保留。 |
+| 🚀 **一键启动** | 双击 `start.cmd` / `start.command` / `start.sh` → 自动构建、启动、打开浏览器。 |
+
+## 🖼️ 长这样
+
+```text
+┌───────────────────────────┬──────────────────────────────────────────────┐
+│ tmuxes                  ⟳ │  ● claude-code — agent1                        │
+│                           │                                                │
+│ ▾ Local            local  │   $ claude "refactor the auth module"          │
+│   📂 frontend             │   ⠿ thinking…                                  │
+│     ● agent1   2 win · 3m │   ▸ Editing src/auth/session.ts                │
+│     ○ agent2   1 win      │   ▸ Running tests…                             │
+│   📁 backend              │                                                │
+│   ○ scratch    1 win      │                                                │
+│ ▾ devbox             ssh  ├───────────────── src/auth/session.ts ─────────┤
+│   ○ build      1 win      │  1  export function createSession(user) {      │
+│ ─────────── drag ──────── │  2    const token = sign(user, KEY)            │
+│ WORKING DIRECTORY     ↑ ⌂ │  3    return { token, exp: Date.now() + TTL }  │
+│   📁 src                  │  4  }                                          │
+│   📄 session.ts           │                                                │
+│   📄 README.md            │                                                │
+│ ⚙ Settings                │                                                │
+└───────────────────────────┴──────────────────────────────────────────────┘
+   侧边栏：tmux 树 + 当前目录文件浏览器          终端  ╱  打开的文件
+```
+
+## 🏗️ 架构
+
+```text
+                          REST  (create · list · rename · kill · cwd · files)
+  ┌────────────┐   ┌──────────────────────┐        ┌──────────────────────────────────┐
+  │  Browser   │──▶│  Node · Express · ws │──pty──▶│ tmux                  (Linux/macOS)│
+  │  xterm.js  │◀──│        node-pty      │──pty──▶│ ssh -tt user@host → tmux   (remote)│
+  └────────────┘   └──────────────────────┘──pty──▶│ wsl.exe -d <distro> → tmux (Windows)│
+        ▲   binary bytes ⇄ WebSocket ⇄ JSON control └──────────────────────────────────┘
+```
+
+- **`client/`** —— React + Vite + TypeScript，终端基于 [`@xterm/xterm`](https://www.npmjs.com/package/@xterm/xterm)。
+- **`server/`** —— Node + Express + `ws` + `node-pty`。一个小型 REST API 跑短命的 tmux *管理*命令；单个 WebSocket 端点负责交互式 *attach* 的流式传输。
+
+> **Windows 上没有原生 tmux？** 没问题。服务端原生运行（node-pty 用 ConPTY），通过 `wsl.exe` 直通你 WSL 发行版里的 tmux。Linux/macOS 上则直接和本地 tmux 通信。远程主机用系统 `ssh` 二进制，复用你已有的 `~/.ssh` 密钥 / `ssh-agent` —— **绝不存储任何密码。**
+
+## 📦 用 npm 安装
+
+```bash
+# 一键运行(无需克隆,自动开浏览器):
+npx tmuxes
+
+# 或全局安装后用 tmuxes 命令:
+npm install -g tmuxes
+tmuxes                       # → http://127.0.0.1:7420
+
+# 常用参数:
+tmuxes --port 8080 --no-open
+```
+
+> 前提:你要连的机器/主机上装了 **tmux**。**Linux** 上 `node-pty` 需现场编译(装 `build-essential` + `python3`);**Windows / macOS** 有预编译二进制,真·一键。详见下方「环境要求」。
+
+## 🚀 从源码一键启动(开发用)
+
+<table>
+<tr><th>系统</th><th>怎么做</th></tr>
+<tr><td><b>🪟 Windows 11</b></td><td>双击 <b><code>start.cmd</code></b>（或在 Windows Terminal 里运行）。自动装依赖、构建、启动服务，并打开 <code>http://127.0.0.1:7420</code>。你的 WSL 发行版会出现在侧边栏。</td></tr>
+<tr><td><b>🍎 macOS</b></td><td>在访达里双击 <b><code>start.command</code></b> <sub>（首次：右键 → 打开，绕过 Gatekeeper）</sub>。</td></tr>
+<tr><td><b>🐧 Linux</b></td><td>运行 <b><code>./start.sh</code></b>。</td></tr>
+</table>
+
+## 🔧 手动运行
+
+```bash
+npm install            # node-pty：Win/macOS 有预编译，Linux 从源码编译
+
+# 开发 —— Vite 开发服务器 + API，带热更新：
+npm run dev            # → http://localhost:5173
+
+# 生产 —— 构建客户端，由单进程统一服务：
+npm run build
+npm start              # → http://localhost:7420   （设 TMUXES_OPEN=1 可自动打开浏览器）
+```
+
+## 🧩 目标（Targets）
+
+- **本地** *(Linux/macOS)* —— 你机器上的 tmux。Windows 上不显示。
+- **Windows 本机终端** *(Windows)* —— 服务端用 ConPTY 直接开 PowerShell / cmd 等本机 shell（自动探测 `pwsh` → `powershell` → `cmd` → Git Bash），新建时可在下拉里选 shell。会话随**服务端进程**存活（刷新 / 重连 / 多标签都不丢，重启服务端会丢）；这类会话没有 tmux 工作目录，故隐藏底部文件浏览器。
+- **WSL 发行版** *(Windows)* —— 通过 `wsl.exe -l -q` 自动发现；每个发行版一个目标。发行版里必须装了 tmux。
+- **SSH 主机** —— 从你的 `~/.ssh/config` 的 `Host` 条目里发现（跳过通配符）。也可显式添加：
+
+  ```bash
+  TMUXES_HOSTS="alice@web1,bob@db2:2222" npm run dev      # Linux / macOS
+  set TMUXES_HOSTS=alice@web1,bob@db2:2222 && npm run dev # Windows cmd
+  ```
+
+  密钥 / agent 认证必须在普通 shell 里已经能用。全新主机请先在普通终端里接受一次它的 host key。
+
+## 💻 环境要求
+
+所有平台都需要 **Node 18+**（开发用的是 22）和 **npm**。其余：
+
+<details>
+<summary><b>🪟 Windows 11</b></summary>
+
+- WSL2 且至少一个发行版，并在其中装好 **tmux**（`sudo apt install tmux`）。
+- 内置的 OpenSSH 客户端覆盖 SSH 目标。
+- node-pty 提供**预编译 Windows 二进制** —— 不需要编译器。
+
+</details>
+
+<details>
+<summary><b>🍎 macOS</b></summary>
+
+- `tmux` 在 `PATH` 上（`brew install tmux`）。
+- node-pty 提供**预编译 darwin 二进制**。
+- 从访达启动却找不到 tmux？确保 Homebrew 的 bin 目录在 GUI 的 `PATH` 里。
+
+</details>
+
+<details>
+<summary><b>🐧 Linux</b></summary>
+
+- `tmux`，外加给 node-pty 的 C/C++ 工具链 + Python 3（**没有 Linux 预编译 —— 安装时现场编译**）：
+  ```bash
+  sudo apt-get install -y build-essential python3 tmux
+  ```
+- WSL 小坑：`node-gyp` 会用 `PATH` 上的任意 `python3`。如果坏掉的 conda Python 把构建搞挂了：
+  ```bash
+  npm config set python /usr/bin/python3
+  ```
+
+</details>
+
+<details>
+<summary><b>（备选）把服务端跑在 WSL 内部</b></summary>
+
+在 Windows 上，你也可以把整个服务端跑在 WSL **内部**（像 Linux 一样），然后在 Windows 上开浏览器 —— WSL2 会转发 `localhost`。一键启动脚本用的是「原生 Windows + `wsl.exe`」方案，这样能在一个地方同时覆盖 SSH 目标和多个发行版。
+
+</details>
+
+## 🔒 安全
+
+> ⚠️ **tmuxes 会把完整的 shell 访问权交给任何能连上它的人。** 它是一个单用户、仅本机的开发工具。
+
+设计上它：
+
+- 只绑定 **`127.0.0.1`** —— 绑定地址在运行时不可配置，
+- **没有任何认证**，
+- **从不起 shell**（argv 数组 + `shell:false`），并对每个输入做白名单校验，
+- 拒绝 `Origin` 非 localhost 的 WebSocket 升级（防 DNS-rebind），
+- 把文件浏览器 / 编辑器限制在所选 tmux 会话的**当前工作目录**之内。
+
+**请勿**对它做反向代理、隧道、端口转发，或暴露到 `0.0.0.0`。机器上任何本地用户都能用它。
+
+## 🧪 测试
+
+```bash
+npm test   # vitest：输入校验、列表解析、ssh/tmux/wsl 的 argv 形状
+```
+
+<div align="center">
+<sub>用 React、TypeScript、node-pty &amp; xterm.js 打造 —— 外加大量 tmux。盯娃愉快。🤖</sub>
+</div>
+
+## 🧑‍🔬 关于作者
+
+> 嗨，我是这个项目的作者 👋
+>
+> 中国科学技术大学（USTC）理论物理在读博士，白天的日常是和**多体场论可解释的费米超流理论**（这玩意是用来研究和解释高温超导的），还有一大坨**高性能数值计算**代码贴身肉搏 ⚛️。
+>
+> 这个小工具其实是被一堆 agent 终端搞到头大之后的「自救产物」—— 既然每天都要盯一群 CLI agent 干活，那干脆给它们造个顺手的指挥台 😎。
+>
+> 如果你也对这些感兴趣（物理也好、代码也好），或者想一起折腾这个开源项目，随时来找我玩 📮
+>
+> **📧 junruwu@mail.ustc.edu.cn**

package/bin/tmuxes.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// tmuxes — web UI to manage tmux sessions (local / SSH / WSL).
+// Parses a couple of flags, sets the env the server reads, then launches it.
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`tmuxes — one browser tab to run and supervise tmux sessions (local · SSH · WSL)
+
+Usage:
+  tmuxes [options]
+
+Options:
+  --port <n>     Port to listen on            (default 7420, env TMUXES_PORT)
+  --host <addr>  Bind address                 (default 127.0.0.1, env TMUXES_HOST)
+  --no-open      Do not open the browser
+  -h, --help     Show this help
+
+Then open http://127.0.0.1:7420 (opens automatically unless --no-open).
+Requires tmux installed on the machine/host you connect to.`);
+  process.exit(0);
+}
+
+function flag(name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+const port = flag('--port');
+if (port) process.env.TMUXES_PORT = port;
+const host = flag('--host');
+if (host) process.env.TMUXES_HOST = host;
+
+// Open the browser by default (the "one-click run" experience), unless the
+// user opted out or already set TMUXES_OPEN.
+if (!args.includes('--no-open') && process.env.TMUXES_OPEN === undefined) {
+  process.env.TMUXES_OPEN = '1';
+}
+
+await import('../dist/index.js');

package/dist/config.js

@@ -0,0 +1,31 @@
+/** Central configuration. Localhost-only by design — see README/SECURITY. */
+export const config = {
+    /** Bind address. Intentionally not configurable: this is a no-auth local shell UI. */
+    host: '127.0.0.1',
+    port: Number(process.env.TMUXES_PORT ?? 7420),
+    /** ssh timeouts (seconds). */
+    ssh: {
+        /** Management calls fail fast so the UI never hangs. */
+        connectTimeoutMgmt: 8,
+        /** Interactive attach is allowed a little longer. */
+        connectTimeoutTty: 10,
+        serverAliveInterval: 30,
+    },
+    /**
+     * Allowed WebSocket Origins. The WS upgrade bypasses Express middleware, so
+     * we enforce this in the upgrade handler to block DNS-rebind / cross-site WS
+     * hijack. Empty/absent Origin (non-browser clients) is allowed.
+     */
+    isAllowedOrigin(origin) {
+        if (!origin)
+            return true;
+        try {
+            const { hostname } = new URL(origin);
+            return hostname === '127.0.0.1' || hostname === 'localhost' || hostname === '[::1]';
+        }
+        catch {
+            return false;
+        }
+    },
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,sFAAsF;IACtF,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC;IAE7C,8BAA8B;IAC9B,GAAG,EAAE;QACH,wDAAwD;QACxD,kBAAkB,EAAE,CAAC;QACrB,qDAAqD;QACrD,iBAAiB,EAAE,EAAE;QACrB,mBAAmB,EAAE,EAAE;KACxB;IAED;;;;OAIG;IACH,eAAe,CAAC,MAA0B;QACxC,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;YACrC,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,OAAO,CAAC;QACtF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACO,CAAC"}

package/dist/exe.js

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, delimiter } from 'node:path';
+import { isWindows } from './platform.js';
+/**
+ * Resolve a command name to a full path for node-pty on Windows.
+ *
+ * Unlike child_process.spawn, node-pty's ConPTY path does NOT search PATH or
+ * append a PATHEXT extension, so `pty.spawn('ssh', …)` fails with
+ * "File not found". We resolve the executable ourselves (PATH + common system
+ * locations). On POSIX, execvp already searches PATH, so the name is returned
+ * unchanged.
+ */
+export function resolveExecutable(file) {
+    if (!isWindows)
+        return file;
+    if (isAbsolute(file) && existsSync(file))
+        return file;
+    const hasExt = /\.[A-Za-z0-9]+$/.test(file);
+    const exts = hasExt ? [''] : (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';');
+    const sysRoot = process.env.SystemRoot || process.env.windir || 'C:\\Windows';
+    const dirs = [
+        ...(process.env.PATH || '').split(delimiter),
+        join(sysRoot, 'System32'),
+        join(sysRoot, 'System32', 'OpenSSH'), // ssh.exe ships here, not always on PATH
+    ];
+    for (const dir of dirs) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = join(dir, file + ext);
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return file; // fall back; node-pty surfaces a clear error if truly missing
+}
+//# sourceMappingURL=exe.js.map

package/dist/exe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exe.js","sourceRoot":"","sources":["../src/exe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtD,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,qBAAqB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvF,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,aAAa,CAAC;IAC9E,MAAM,IAAI,GAAG;QACX,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;QAC5C,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC;QACzB,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,yCAAyC;KAChF,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,GAAG,CAAC,CAAC;YACxC,IAAI,UAAU,CAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAC;QAC9C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,8DAA8D;AAC7E,CAAC"}

package/dist/exec.js

@@ -0,0 +1,43 @@
+import { spawn } from 'node:child_process';
+/**
+ * Run a command as an argv array with NO shell. Never rejects — a nonzero exit
+ * or spawn error resolves with the captured output so callers can interpret it
+ * (e.g. tmux "no server running" is a normal empty case, not a throw).
+ */
+export function runCommand(file, args, opts = {}) {
+    const encoding = opts.encoding ?? 'utf8';
+    return new Promise((resolve) => {
+        const child = spawn(file, args, { shell: false });
+        const outChunks = [];
+        const errChunks = [];
+        let settled = false;
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                child.kill('SIGKILL');
+            }, opts.timeoutMs)
+            : null;
+        child.stdout.on('data', (d) => outChunks.push(d));
+        child.stderr.on('data', (d) => errChunks.push(d));
+        if (opts.input !== undefined) {
+            child.stdin.on('error', () => {
+                /* ignore EPIPE if the child exits early */
+            });
+            child.stdin.end(opts.input);
+        }
+        const done = (code, signal, extraErr) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            const stderr = Buffer.concat(errChunks).toString(encoding) + (extraErr ?? '');
+            resolve({ code, signal, stdout: Buffer.concat(outChunks).toString(encoding), stderr });
+        };
+        child.on('error', (err) => {
+            // e.g. ENOENT when ssh/tmux/wsl.exe is missing — surface as a failed result.
+            done(null, null, err.message);
+        });
+        child.on('close', (code, signal) => done(code, signal));
+    });
+}
+//# sourceMappingURL=exec.js.map

package/dist/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAiB3C;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAc,EAAE,OAAmB,EAAE;IAC5E,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC;IACzC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS;YAC1B,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE;gBACd,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACxB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC;YACpB,CAAC,CAAC,IAAI,CAAC;QAET,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAE1D,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;gBAC3B,2CAA2C;YAC7C,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,IAAmB,EAAE,MAA6B,EAAE,QAAiB,EAAE,EAAE;YACrF,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;YAC9E,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QACzF,CAAC,CAAC;QAEF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACxB,6EAA6E;YAC7E,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/files.js

@@ -0,0 +1,250 @@
+import { promises as fsp } from 'node:fs';
+import { basename as posixBasename, dirname as posixDirname } from 'node:path/posix';
+import { runCommand } from './exec.js';
+import { commandArgv } from './tmux/builder.js';
+import { TmuxError } from './tmux/sessions.js';
+const REMOTE_TIMEOUT_MS = 15_000;
+/** Max bytes returned for a file preview. */
+export const FILE_PREVIEW_CAP = 2_000_000;
+/** A NUL anywhere in a preview means the file is binary. */
+const NUL = String.fromCharCode(0);
+function timeout(t) {
+    return t.kind === 'local' ? undefined : REMOTE_TIMEOUT_MS;
+}
+function normalizeRoot(path) {
+    if (path === '/')
+        return path;
+    return path.replace(/\/+$/, '');
+}
+export function isInsideRoot(root, candidate) {
+    const normalizedRoot = normalizeRoot(root);
+    return normalizedRoot === '/' || candidate === normalizedRoot || candidate.startsWith(`${normalizedRoot}/`);
+}
+async function remoteRealpath(t, path) {
+    const r = await run(t, ['realpath', path]);
+    if (r.code !== 0) {
+        if (/No such file|not found/i.test(r.stderr))
+            throw new TmuxError(404, 'path not found');
+        if (/Permission denied/i.test(r.stderr))
+            throw new TmuxError(403, 'permission denied');
+        throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot resolve path');
+    }
+    const resolved = r.stdout.trim().split('\n')[0];
+    if (!resolved)
+        throw new TmuxError(502, 'empty resolved path');
+    return resolved;
+}
+async function realpath(t, path) {
+    if (t.kind === 'local') {
+        try {
+            return await fsp.realpath(path);
+        }
+        catch (e) {
+            throw fsError(e, path);
+        }
+    }
+    return remoteRealpath(t, path);
+}
+async function tryRealpath(t, path) {
+    try {
+        return await realpath(t, path);
+    }
+    catch (e) {
+        if (e instanceof TmuxError && e.status === 404)
+            return null;
+        throw e;
+    }
+}
+/**
+ * Resolve a requested target path and verify it stays inside the session's cwd.
+ * This keeps the file browser/editor scoped to the agent workspace instead of
+ * exposing arbitrary host files through the no-auth local server.
+ */
+export async function resolveScopedPath(t, rootPath, requestedPath, opts = {}) {
+    if (!requestedPath.startsWith('/'))
+        throw new TmuxError(400, 'path must be absolute');
+    const root = await realpath(t, rootPath);
+    let candidate = null;
+    if (opts.forWrite) {
+        candidate = await tryRealpath(t, requestedPath);
+        if (!candidate) {
+            const name = posixBasename(requestedPath);
+            if (!name || name === '.' || name === '..')
+                throw new TmuxError(400, 'invalid path');
+            const parent = await realpath(t, posixDirname(requestedPath));
+            candidate = parent === '/' ? `/${name}` : `${parent}/${name}`;
+        }
+    }
+    else {
+        candidate = await realpath(t, requestedPath);
+    }
+    if (!isInsideRoot(root, candidate)) {
+        throw new TmuxError(403, 'path is outside the session working directory');
+    }
+    return candidate;
+}
+async function run(t, argv) {
+    const { file, args } = commandArgv(t, argv);
+    return runCommand(file, args, { timeoutMs: timeout(t) });
+}
+/** The working directory of a session's active pane (tmux #{pane_current_path}). */
+export async function getSessionCwd(t, session) {
+    const { file, args } = commandArgv(t, [
+        'tmux',
+        'display-message',
+        '-p',
+        '-t',
+        session,
+        '#{pane_current_path}',
+    ]);
+    const r = await runCommand(file, args, { timeoutMs: timeout(t) });
+    if (r.code !== 0) {
+        if (/can't find|no server running|session not found/i.test(r.stderr)) {
+            throw new TmuxError(404, `session "${session}" not found`);
+        }
+        throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot read session cwd');
+    }
+    const cwd = r.stdout.trim();
+    if (!cwd)
+        throw new TmuxError(502, 'empty session cwd');
+    return cwd;
+}
+function sortEntries(entries) {
+    return entries.sort((a, b) => {
+        if (a.type !== b.type)
+            return a.type === 'dir' ? -1 : 1;
+        return a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: 'base' });
+    });
+}
+/** List a directory ON THE TARGET. Local uses fs; wsl/ssh shell out to `ls`. */
+export async function listDirectory(t, path) {
+    if (t.kind === 'local') {
+        let dirents;
+        try {
+            dirents = await fsp.readdir(path, { withFileTypes: true });
+        }
+        catch (e) {
+            throw fsError(e, path);
+        }
+        const entries = [];
+        for (const d of dirents) {
+            if (d.name.startsWith('.') && (d.name === '.' || d.name === '..'))
+                continue;
+            let isDir = d.isDirectory();
+            if (d.isSymbolicLink()) {
+                // Resolve symlinks so linked dirs are navigable.
+                try {
+                    const st = await fsp.stat(path.replace(/\/$/, '') + '/' + d.name);
+                    isDir = st.isDirectory();
+                }
+                catch {
+                    isDir = false;
+                }
+            }
+            entries.push({ name: d.name, type: isDir ? 'dir' : 'file' });
+        }
+        return sortEntries(entries);
+    }
+    // wsl/ssh: `ls -Ap1 -- <path>` → one per line, dirs end with "/".
+    const r = await run(t, ['ls', '-Ap1', '--', path]);
+    if (r.code !== 0) {
+        if (/No such file|not found/i.test(r.stderr))
+            throw new TmuxError(404, 'directory not found');
+        if (/Permission denied/i.test(r.stderr))
+            throw new TmuxError(403, 'permission denied');
+        throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot list directory');
+    }
+    const entries = r.stdout
+        .split('\n')
+        .filter((l) => l.length > 0)
+        .map((line) => {
+        const isDir = line.endsWith('/');
+        const name = isDir ? line.slice(0, -1) : line;
+        return { name, type: isDir ? 'dir' : 'file' };
+    })
+        .filter((e) => e.name && e.name !== '.' && e.name !== '..');
+    return sortEntries(entries);
+}
+/** Read a (capped) file preview ON THE TARGET. */
+export async function readFilePreview(t, path) {
+    if (t.kind === 'local') {
+        let fh;
+        try {
+            fh = await fsp.open(path, 'r');
+        }
+        catch (e) {
+            throw fsError(e, path);
+        }
+        try {
+            const st = await fh.stat();
+            if (st.isDirectory())
+                throw new TmuxError(400, 'path is a directory');
+            const cap = FILE_PREVIEW_CAP;
+            const buf = Buffer.alloc(Math.min(cap, Number(st.size)));
+            const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+            const slice = buf.subarray(0, bytesRead);
+            return {
+                path,
+                content: slice.toString('utf8'),
+                truncated: st.size > cap,
+                binary: slice.includes(0),
+            };
+        }
+        finally {
+            await fh.close();
+        }
+    }
+    // wsl/ssh: read up to cap+1 bytes; if we got cap+1 the file is larger.
+    const r = await run(t, ['head', '-c', String(FILE_PREVIEW_CAP + 1), '--', path]);
+    if (r.code !== 0) {
+        if (/No such file|not found/i.test(r.stderr))
+            throw new TmuxError(404, 'file not found');
+        if (/Is a directory/i.test(r.stderr))
+            throw new TmuxError(400, 'path is a directory');
+        if (/Permission denied/i.test(r.stderr))
+            throw new TmuxError(403, 'permission denied');
+        throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot read file');
+    }
+    const truncated = r.stdout.length > FILE_PREVIEW_CAP;
+    const content = truncated ? r.stdout.slice(0, FILE_PREVIEW_CAP) : r.stdout;
+    return { path, content, truncated, binary: content.includes(NUL) };
+}
+/** Overwrite a file ON THE TARGET with `content` (UTF-8). Local uses fs;
+ *  wsl/ssh pipe the bytes into `tee -- <path>` over stdin (tee truncates). */
+export async function writeFile(t, path, content) {
+    if (t.kind === 'local') {
+        try {
+            await fsp.writeFile(path, content, 'utf8');
+        }
+        catch (e) {
+            throw fsError(e, path);
+        }
+        return;
+    }
+    // `tee` opens the file with O_TRUNC|O_CREAT, so shorter content can't leave a
+    // stale tail. Its stdout echo of the content is ignored.
+    const { file, args } = commandArgv(t, ['tee', '--', path]);
+    const r = await runCommand(file, args, { timeoutMs: REMOTE_TIMEOUT_MS, input: content });
+    if (r.code !== 0) {
+        if (/No such file|not found/i.test(r.stderr))
+            throw new TmuxError(404, 'directory not found');
+        if (/Is a directory/i.test(r.stderr))
+            throw new TmuxError(400, 'path is a directory');
+        if (/Permission denied/i.test(r.stderr))
+            throw new TmuxError(403, 'permission denied');
+        throw new TmuxError(502, r.stderr.trim().split('\n')[0] || 'cannot write file');
+    }
+}
+function fsError(e, path) {
+    const code = e?.code;
+    if (code === 'ENOENT')
+        return new TmuxError(404, `not found: ${path}`);
+    if (code === 'EACCES')
+        return new TmuxError(403, `permission denied: ${path}`);
+    if (code === 'ENOTDIR')
+        return new TmuxError(400, `not a directory: ${path}`);
+    if (code === 'EISDIR')
+        return new TmuxError(400, `path is a directory: ${path}`);
+    return new TmuxError(502, e instanceof Error ? e.message : 'filesystem error');
+}
+//# sourceMappingURL=files.js.map