@znmin/claude-remote-cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# claude-remote-cli
 
-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.
+在本地任意项目目录运行 `claude`，自动将目录双向同步到你指定的 SSH 服务器，并在服务器上运行真正的 Claude Code。
+
+本项目是独立的 SSH/同步封装，不是 Anthropic 官方客户端。它不提供服务器、Claude 账号或 API 服务。
+
+## 安装
+
+要求：Node.js **20.11 或更高版本**、npm、OpenSSH（`ssh`/`scp`）和系统 `tar`。支持 macOS/Linux 的 x64、arm64；Windows 请在 WSL 内安装使用。本地无需 Python、Homebrew 或 Claude Code。
+
+npm 包名为 `@znmin/claude-remote-cli`，安装后提供 `claude` 和 `claude-remote` 命令。
+
+通过 npm 安装：
+
+```bash
+npm install -g @znmin/claude-remote-cli
+```
+
+也可以直接从 GitHub 安装：
+
+```bash
+npm install -g git+https://github.com/znmin/claude-remote-cli.git
+```
+
+也可以从已下载的分发包安装：
+
+```bash
+npm install -g ./znmin-claude-remote-cli-0.1.1.tgz
+```
+
+若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.1.1.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
+
+npm 中不带作用域的 `claude-remote-cli` 属于其他项目。本项目使用独立的 `@znmin/claude-remote-cli` 作用域包名；请安装完整包名，或使用上述 GitHub 地址及本项目分发的 `.tgz` 文件。
+
+安装会自动准备 Mutagen 同步工具：复用 PATH 中的 0.18.1 版本，或从官方 GitHub Release 下载固定版本并校验内置 SHA-256。下载需要网络，工具和远程代理合计占用约百 MB 磁盘。安装时网络不可用不会让 npm 安装失败，第一次连接时会重试。
+
+如果用户已经安装其他提供 `claude` 命令的软件，应先卸载旧客户端，避免 npm 命令冲突或 PATH 指向旧程序。无需使用 `--force` 覆盖。
+
+## 开始使用
+
+服务器需要 Linux/macOS、可用的 SSH/SCP 和 Bash。启动时会检查 Claude Code：
+
+- 已安装：直接使用已有程序。
+- 默认 `claude` 命令不存在：通过服务器上的 `curl` 或 `wget` 下载并执行 [Anthropic 官方原生安装器](https://github.com/anthropics/claude-code#get-started)，无需服务器安装 Node.js，也不会使用 `sudo`。
+- 安装完成：检查命令已可用，再开始目录同步并启动 Claude。首次启动时按 Claude 的提示完成账号认证；不会复制本机账号凭据。
+- 下载失败、安装失败或缺少 `curl`/`wget`：停止启动并报告原因，不建立新的项目同步会话。自动安装最多等待 10 分钟，可修复网络/权限后重试。
+
+安装过程只在默认命令缺失时触发，不会自动重装或升级已有 Claude Code。
+
+```bash
+# 配置你的服务器，不会立即连接或上传文件
+claude-remote configure user@example.com
+
+# 自定义 SSH 端口
+claude-remote configure user@example.com --port 2222
+
+# 也支持 ~/.ssh/config 中的别名，包括密钥和跳板机设置
+claude-remote configure my-server
+
+# 在任意具体项目目录运行
+cd /path/to/project
+claude
+
+# 参数直接传递给远程 Claude Code
+claude --continue
+```
+
+未配置服务器时，也可以直接运行 `claude`，按终端提示输入服务器地址和端口。请勿把密码或私钥填入配置；登录使用 OpenSSH 原有认证流程和主机身份验证。
+
+若需要使用特定的 Claude 可执行文件，可指定绝对路径；自定义路径不存在时会提示修正配置，不会自动改用其他程序：
+
+```bash
+claude-remote configure my-server --claude /absolute/path/to/claude
+```
+
+## 同步管理
+
+```bash
+claude-remote status               # 查看全部项目、同步错误和文件冲突
+claude-remote flush                # 等待当前项目完成一次同步
+claude-remote stop                 # 停止当前目录在当前配置服务器上的同步
+claude-remote stop --all           # 停止本工具的所有同步会话
+claude-remote stop --name 名称     # 按 status 中的名称停止旧服务器上的映射
+claude-remote doctor               # 检查本地安装和服务器配置，不连接服务器
+claude-remote install-sync         # 手动重试同步工具准备
+claude-remote --help
+```
+
+退出 Claude 后继续后台同步，`stop` 会终止映射并保留两端文件。切换服务器前，先停止旧映射；`configure` 不会自动停止它们。映射的同一个目录及其父子目录不允许同时连到多个服务器。
+
+可以临时覆盖服务器，配置文件保持不变：
+
+```bash
+CLAUDE_REMOTE_HOST=another-server CLAUDE_REMOTE_PORT=2222 claude
+```
+
+## 文件行为
+
+- 每台本机、每个 SSH 地址/端口、每个项目目录有独立的稳定编号，远程默认映射到 `~/.local/share/claude-remote/projects/<编号>`。启动时会显示两端路径。移动项目或更换 SSH 别名会产生新的编号。
+- 启动远程 Claude 前等待首次同步，退出时也尝试完成一次同步。连接或最终同步失败会返回非零退出码；会话保留以便检查和重连。
+- 使用 `two-way-safe` 双向同步。两边同时改同一文件会保留冲突，不自动选择覆盖版本。通过 `status` 查看路径，备份需要的内容，手动将两边统一，再运行 `flush`。运行期间可在另一个终端查看状态。
+- 正常修改和删除都会双向传播。此工具不提供文件版本备份。
+- 默认忽略 `.DS_Store`、`node_modules`、`.venv`、`__pycache__`，项目依赖需在服务器安装。
+- 其他文件（包括 `.env`、未提交文件及普通仓库的 `.git`）默认同步；不自动读取 `.gitignore`。尽量避免两端同时执行 Git 写操作。
+- 支持配置额外忽略规则：`claude-remote configure my-server --ignore '.env*' --ignore 'dist'`。忽略配置仅在新建映射时生效，修改后应先停止旧映射再启动。
+- 可通过 `--root /srv/claude-projects` 自定义远程父目录。不会直接占用服务器的既有同名项目目录。
+- 同步存在网络和扫描延迟，不等同于共享磁盘。Git worktree/子模块的 `.git` 外部引用暂不支持；指向目录外的符号链接也可能无法同步。macOS/Linux 间的文件名大小写差异可能产生冲突。
+- 不允许同步整个本机用户目录或磁盘根目录。不会同步用户目录中的 Claude 登录信息；远程使用自己的登录状态和工具配置。
+- 本版不提供 tmux 会话恢复。网络中断后文件同步会尝试重连，远程 Claude 进程是否继续运行取决于服务器的进程行为。
+
+## 高级环境变量
+
+| 变量 | 用途 |
+| --- | --- |
+| `CLAUDE_REMOTE_HOST` | 临时 SSH 别名或 user@host |
+| `CLAUDE_REMOTE_PORT` | 临时 SSH 端口 |
+| `CLAUDE_REMOTE_CONFIG_DIR` | 配置和映射索引目录，默认 `~/.config/claude-remote` |
+| `CLAUDE_REMOTE_CACHE_DIR` | 下载缓存父目录，默认 `~/.cache/claude-remote` |
+| `CLAUDE_REMOTE_MUTAGEN` | 使用自行准备的 Mutagen 可执行文件绝对路径（应为 0.18.1，并放置配套代理包） |
+| `CLAUDE_REMOTE_SKIP_DOWNLOAD=1` | npm 安装阶段跳过准备，首次连接时仍会自动准备 |
+| `CLAUDE_REMOTE_DEBUG=1` | 出错时显示调试信息 |
+
+`npm install --ignore-scripts` 也受支持，首次连接会补装同步工具。无法访问 GitHub 时，可先在可联网环境准备工具，或使用 `CLAUDE_REMOTE_MUTAGEN` 指向完整的本机安装。
+
+卸载：先用 `claude-remote stop --all` 停止后台同步，再 `npm uninstall -g @znmin/claude-remote-cli`。npm 卸载保留本地配置、缓存和两端项目文件。
+
+## 开发、打包与发布
+
+```bash
+npm ci --ignore-scripts
+npm test
+
+# 可选：本机真实 Mutagen 双向同步与冲突测试
+CLAUDE_REMOTE_INTEGRATION=1 npm test
+
+npm pack
+npm install -g ./znmin-claude-remote-cli-0.1.1.tgz
+
+# 确定包名、版本和使用条款后，使用有发布权限的 npm 账号发布
+npm login
+npm publish --access public
+```
+
+GitHub 仓库名为 `claude-remote-cli`，npm 包名为 `@znmin/claude-remote-cli`，命令名为 `claude` 和 `claude-remote`。发布账号必须拥有 npm 用户作用域 `@znmin`，或拥有同名 npm 组织的发布权限；GitHub 身份不会自动授予 npm 权限。当前 `license` 为 `UNLICENSED`，尚未指定开源许可证。
+
+测试覆盖全局安装、命令入口、项目隔离、参数引用、冲突阻断、下载校验、本地真实双向同步，以及使用隔离环境模拟的远程自动安装、下载失败和安装失败。由于尚未提供服务器，真实 SSH 认证、服务器上的官方安装与 Claude 交互、Linux 和其他 CPU 架构尚未实测。
+
+参考：[npm 命令入口配置](https://docs.npmjs.com/cli/configuring-npm/package-json#bin)、[Mutagen 同步机制](https://mutagen.io/documentation/synchronization/)、[Mutagen SSH 支持](https://mutagen.io/documentation/transports/ssh/)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,14 @@
+# Third-party components
+
+The npm package contains the JavaScript CLI source and depends on `proper-lockfile` (MIT) and its npm-managed dependencies. Their license files are included in their respective npm packages.
+
+Mutagen binaries are **not bundled in this npm package**. At setup/first use, the tool can reuse an existing Mutagen 0.18.1 installation, or download the matching v0.18.1 archive from the official release repository. SHA-256 values are pinned in `src/installer.js` from the official release's `SHA256SUMS` file.
+
+- Mutagen project: https://github.com/mutagen-io/mutagen
+- Pinned release: https://github.com/mutagen-io/mutagen/releases/tag/v0.18.1
+- Release checksums: https://github.com/mutagen-io/mutagen/releases/download/v0.18.1/SHA256SUMS
+- Upstream license: https://github.com/mutagen-io/mutagen/blob/v0.18.1/LICENSE
+
+The upstream license states that, from v0.17 onward, official release builds include SSPL-licensed code by default; other source is generally MIT or as indicated upstream. Mutagen and the automatically deployed remote agents remain subject to the upstream terms independently of this JavaScript wrapper.
+
+Claude Code is a separate product installed and authenticated on the user's server. This project does not bundle Claude Code and is not affiliated with or endorsed by Anthropic.

package/bin/claude-remote.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { entry } from '../src/cli.js';
+await entry(false);

package/bin/claude.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { entry } from '../src/cli.js';
+await entry(true);

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@znmin/claude-remote-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Run Claude Code on your SSH server with safe bidirectional project synchronization",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20.11"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "bin": {
+    "claude": "bin/claude.js",
+    "claude-remote": "bin/claude-remote.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/postinstall.js",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "claude",
+    "ssh",
+    "remote",
+    "cli",
+    "sync"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "proper-lockfile": "4.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/znmin/claude-remote-cli.git"
+  },
+  "homepage": "https://github.com/znmin/claude-remote-cli#readme",
+  "bugs": {
+    "url": "https://github.com/znmin/claude-remote-cli/issues"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,11 @@
+import { ensureMutagen } from '../src/installer.js';
+
+if (process.env.CLAUDE_REMOTE_SKIP_DOWNLOAD !== '1') {
+  try {
+    await ensureMutagen();
+    console.log('claude 已安装。运行 claude-remote configure 用户名@服务器，或直接运行 claude 开始配置。');
+  } catch (error) {
+    // Offline installation and npm --ignore-scripts remain supported: retry at first use.
+    console.warn(`CLI 已安装，同步工具准备未完成：${error.message}\n首次连接时会重试。`);
+  }
+}

package/src/cli.js

@@ -0,0 +1,94 @@
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import { Client, DEFAULTS } from './client.js';
+import { cachedBinary, ensureMutagen, VERSION } from './installer.js';
+import { exists, readJSON, which } from './system.js';
+
+const HELP = `@znmin/claude-remote-cli 0.1.1（非 Anthropic 官方客户端）
+
+安装后使用：
+  claude                           首次引导设置服务器，之后启动远程 Claude Code
+  claude --continue                将参数传给服务器上的 Claude
+  claude-remote configure [user@host] [--port 2222] [--claude /路径/claude]
+  claude-remote status              查看全部同步状态和冲突
+  claude-remote flush               等待当前目录同步完成
+  claude-remote stop [--all | --name 名称]
+  claude-remote doctor              检查本地环境，不连接服务器
+  claude-remote install-sync        准备同步工具（通常自动完成）
+  claude-remote run [Claude 参数]   启动远程 Claude
+
+configure 可选：--root 远程根目录、--ignore 忽略规则（可重复）。
+服务器缺少默认 Claude Code 时会自动安装；首次启动需完成认证。
+此工具不提供服务器或 Claude 账号。
+退出 Claude 后会继续后台同步；停止请运行 claude-remote stop。
+`;
+
+async function configure(client, args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    port: { type: 'string' }, root: { type: 'string' }, claude: { type: 'string' },
+    ignore: { type: 'string', multiple: true }
+  } });
+  if (positionals.length > 1) throw new Error('仅接受一个 SSH 别名或 user@host。');
+  let host = positionals[0], port = values.port;
+  if (!host) {
+    if (!process.stdin.isTTY) throw new Error('请指定服务器：claude-remote configure 用户名@服务器');
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      console.log('设置你的 SSH 服务器（不要填写密码或私钥）。');
+      host = (await prompt.question('SSH 别名或 user@host：')).trim();
+      if (port === undefined) port = (await prompt.question('端口（留空使用 SSH 默认配置）：')).trim() || undefined;
+    } finally { prompt.close(); }
+  }
+  return client.configure({ host, port: port === undefined ? null : Number(port),
+    root: values.root || DEFAULTS.root, claude: values.claude || DEFAULTS.claude, ignores: values.ignore || [] });
+}
+
+export async function main(asClaude, args = process.argv.slice(2), client = new Client()) {
+  if (asClaude) {
+    const saved = await readJSON(client.configFile, {});
+    if (!saved.host && !client.env.CLAUDE_REMOTE_HOST) {
+      if (args.includes('--help') || args.includes('-h')) { console.log(HELP); return 0; }
+      if (args.includes('--version')) { console.log('@znmin/claude-remote-cli 0.1.1'); return 0; }
+      if (process.stdin.isTTY) await configure(client, []);
+    }
+    return client.launch(await client.settings(), args);
+  }
+  const [action, ...rest] = args;
+  if (!action || ['--help', '-h', 'help'].includes(action)) { console.log(HELP); return 0; }
+  if (['--version', '-v'].includes(action)) { console.log('0.1.1'); return 0; }
+  if (action === 'configure') { await configure(client, rest); return 0; }
+  if (action === 'run') return client.launch(await client.settings(), rest[0] === '--' ? rest.slice(1) : rest);
+  if (action === 'stop') {
+    const { values, positionals } = parseArgs({ args: rest, allowPositionals: true,
+      options: { all: { type: 'boolean' }, name: { type: 'string' } } });
+    if (positionals.length || values.all && values.name) throw new Error('用法：claude-remote stop [--all | --name 名称]');
+    await client.stop(values); return 0;
+  }
+  if (rest.length) throw new Error(`${action} 不接受额外参数。`);
+  if (action === 'status') {
+    await client.sync(['list', '--long', '--label-selector', 'claude-remote=true'], { capture: false }); return 0;
+  }
+  if (action === 'flush') {
+    await client.flush((await client.project(await client.settings())).name); return 0;
+  }
+  if (action === 'install-sync') { console.log('同步工具：' + await ensureMutagen({ env: client.env })); return 0; }
+  if (action === 'doctor') {
+    console.log(`Node.js：${process.version}\n平台：${process.platform}/${process.arch}`);
+    for (const tool of ['ssh', 'scp', 'tar']) console.log(`${tool}：${await which(tool, client.env.PATH) || '未安装'}`);
+    const cached = cachedBinary(client.env);
+    console.log(`同步工具：${client.env.CLAUDE_REMOTE_MUTAGEN || (await exists(cached) ? cached : await which('mutagen', client.env.PATH)) || '首次使用时自动下载'}（目标版本 ${VERSION}）`);
+    const config = await readJSON(client.configFile, {});
+    console.log(`配置：${client.configFile}\n服务器：${client.env.CLAUDE_REMOTE_HOST || config.host || '尚未配置'}`);
+    return 0;
+  }
+  throw new Error(`未知命令 ${action}。运行 claude-remote --help 查看用法。`);
+}
+
+export async function entry(asClaude) {
+  try { process.exitCode = await main(asClaude); }
+  catch (error) {
+    console.error('claude-remote：' + error.message);
+    if (process.env.CLAUDE_REMOTE_DEBUG === '1') console.error(error.stack);
+    process.exitCode = 1;
+  }
+}

package/src/client.js

@@ -0,0 +1,208 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+import { execute, exists, quote, readJSON, shellJoin, which, withLock, writeJSON } from './system.js';
+import { ensureMutagen } from './installer.js';
+import { ensureRemoteClaude, remoteEnvironment as prefix } from './remote-claude.js';
+
+export const DEFAULTS = {
+  root: '.local/share/claude-remote/projects', claude: 'claude',
+  ignores: ['.DS_Store', 'node_modules', '.venv', '__pycache__']
+};
+
+export function validate(config) {
+  if (!/^(?:[A-Za-z0-9_][A-Za-z0-9_.-]*@)?[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(config.host || ''))
+    throw new Error('服务器请填写 SSH 别名或 user@host，不要包含端口、空格或 SSH 参数。IPv6 请使用 SSH 别名。');
+  if (config.port != null && (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535))
+    throw new Error('端口必须在 1–65535 之间。');
+  if (typeof config.root !== 'string' || !/^\/?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(config.root) ||
+      config.root.split('/').some(part => ['.', '..'].includes(part)))
+    throw new Error('远程根目录仅支持字母、数字、点、短横线、下划线和斜杠，不支持 ..。');
+  if (typeof config.claude !== 'string' || !config.claude || /[\r\n\0]/.test(config.claude) || config.claude.startsWith('-'))
+    throw new Error('远程 Claude 程序路径无效。');
+  if (!Array.isArray(config.ignores) || config.ignores.some(pattern => typeof pattern !== 'string' || !pattern))
+    throw new Error('忽略规则需要是非空字符串列表。');
+  if (config.client_id != null && (typeof config.client_id !== 'string' || !config.client_id))
+    throw new Error('配置文件中的 client_id 无效。');
+  return config;
+}
+
+export const remotePath = file => file.startsWith('/') ? quote(file) : '"$HOME"/' + quote(file);
+
+export function sshArgs(config, script, { interactive = false, tty = false } = {}) {
+  const args = ['-o', 'ConnectTimeout=15', '-o', 'ServerAliveInterval=15', '-o', 'ServerAliveCountMax=3'];
+  if (!interactive) args.push('-n'); // Never consume piped Claude prompts during preflight.
+  if (tty) args.push('-tt');
+  if (config.port != null) args.push('-p', String(config.port));
+  args.push(config.host, 'bash -lc ' + quote(script));
+  return args;
+}
+
+export function assertSynchronized(current) {
+  if (!current) throw new Error('同步会话不存在。');
+  if (current.conflicts?.length || current.excludedConflicts)
+    throw new Error('发现双向修改冲突，未自动覆盖。运行 claude-remote status 查看路径，备份后将两边文件统一，再运行 claude-remote flush。');
+  for (const side of ['alpha', 'beta']) {
+    const state = current[side] || {};
+    if (state.scanProblems?.length || state.transitionProblems?.length || state.excludedScanProblems || state.excludedTransitionProblems)
+      throw new Error('同步端点有文件处理错误，请运行 claude-remote status 查看详情。');
+    if (state.connected === false) throw new Error('同步端点已断开，请检查连接后重试。');
+  }
+  if (current.lastError) throw new Error('同步尚有错误：' + current.lastError);
+  if (current.paused) throw new Error('同步会话已暂停，请重新运行 claude 恢复。');
+}
+
+export class Client {
+  constructor(options = {}) {
+    this.env = options.env || process.env;
+    this.home = options.home || os.homedir();
+    this.cwd = options.cwd || process.cwd();
+    this.directory = options.configDir || this.env.CLAUDE_REMOTE_CONFIG_DIR || path.join(this.home, '.config', 'claude-remote');
+    this.configFile = path.join(this.directory, 'config.json');
+    this.registryFile = path.join(this.directory, 'projects.json');
+    this.lockFile = path.join(this.directory, 'npm-state');
+    this.execute = options.execute || execute;
+    this.ensureMutagen = options.ensureMutagen || ensureMutagen;
+    this.log = options.log || console.error;
+    this.warn = options.warn || console.error;
+    this.tty = options.tty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  }
+
+  async configure(input) {
+    return withLock(this.lockFile, async () => {
+      const old = await readJSON(this.configFile, {});
+      const config = validate({ ...DEFAULTS, ...input,
+        ignores: [...DEFAULTS.ignores, ...(input.ignores || [])],
+        client_id: old.client_id || randomUUID().replaceAll('-', '').slice(0, 12) });
+      await writeJSON(this.configFile, config);
+      this.log(`已配置服务器：${config.host}。进入项目目录后运行 claude。`);
+      this.log('旧服务器的后台同步不会自动停止；切换前可运行 claude-remote stop --all。');
+      return config;
+    });
+  }
+
+  async settings() {
+    return withLock(this.lockFile, async () => {
+      const stored = await readJSON(this.configFile, {});
+      const config = { ...DEFAULTS, ...stored };
+      if (this.env.CLAUDE_REMOTE_HOST) config.host = this.env.CLAUDE_REMOTE_HOST;
+      if (this.env.CLAUDE_REMOTE_PORT !== undefined) config.port = Number(this.env.CLAUDE_REMOTE_PORT);
+      if (!config.host) throw new Error('尚未配置服务器。请运行：claude-remote configure 用户名@服务器（自定义端口加 --port 2222）。');
+      validate(config);
+      if (!config.client_id) {
+        config.client_id = randomUUID().replaceAll('-', '').slice(0, 12);
+        // Temporary environment overrides must not change the saved server.
+        await writeJSON(this.configFile, { ...stored, client_id: config.client_id });
+      }
+      return config;
+    });
+  }
+
+  async project(config) {
+    const local = await fs.realpath(this.cwd);
+    const home = await fs.realpath(this.home);
+    if (local === home || local === path.parse(local).root)
+      throw new Error('请进入具体项目目录；不允许同步整个用户目录或磁盘根目录。');
+    const git = path.join(local, '.git');
+    if (await exists(git) && (await fs.stat(git)).isFile())
+      throw new Error('当前目录的 .git 指向外部仓库，暂不支持 Git worktree/子模块；请使用普通独立仓库。');
+    // Keep the original Python implementation's stable project identifiers.
+    const identity = '[' + [config.client_id, config.host, config.port ?? null, config.root, local]
+      .map(value => JSON.stringify(value)).join(', ') + ']';
+    const key = createHash('sha256').update(identity).digest('hex').slice(0, 24);
+    return { name: 'claude-remote-' + key, local, remote: config.root + '/' + key,
+      host: config.host, port: config.port ?? null };
+  }
+
+  async prepare() {
+    if (!this.mutagen) this.mutagen = await this.ensureMutagen({ env: this.env });
+    return this.mutagen;
+  }
+
+  async sync(args, options = {}) {
+    const binary = await this.prepare();
+    return this.execute(binary, ['sync', ...args], { env: this.env, capture: true, ...options });
+  }
+
+  async sessions() {
+    const result = await this.sync(['list', '--label-selector', 'claude-remote=true', '--template', '{{json .}}'],
+      { capture: true, timeout: 30000 });
+    return JSON.parse(result.stdout) || [];
+  }
+
+  async flush(name) {
+    await this.sync(['flush', name], { timeout: 120000 });
+    assertSynchronized((await this.sessions()).find(session => session.name === name));
+  }
+
+  async remote(config, script, interactive = false, { timeout = 180000 } = {}) {
+    return this.execute('ssh', sshArgs(config, script, { interactive, tty: interactive && this.tty }),
+      { env: this.env, timeout: interactive ? 0 : timeout, check: !interactive });
+  }
+
+  async launch(config, extra) {
+    for (const tool of ['ssh', 'scp']) if (!await which(tool, this.env.PATH))
+      throw new Error(`找不到系统 ${tool}，请安装 OpenSSH 客户端。`);
+    const item = await this.project(config);
+    await this.prepare();
+    await withLock(this.lockFile, async () => {
+      const existing = await this.sessions();
+      const registry = await readJSON(this.registryFile, {});
+      for (const session of existing) {
+        if (session.name === item.name) continue;
+        const storedPath = session.alpha?.path || registry[session.name]?.local;
+        if (!storedPath) continue;
+        let other;
+        try { other = await fs.realpath(storedPath); }
+        catch (error) { if (error.code !== 'ENOENT') throw error; other = path.resolve(storedPath); }
+        const relative = path.relative(other, item.local);
+        const reverse = path.relative(item.local, other);
+        const inside = value => value === '' || (!value.startsWith('..' + path.sep) && value !== '..' && !path.isAbsolute(value));
+        if (inside(relative) || inside(reverse))
+          throw new Error(`目录与正在同步的项目重叠：${other}\n先运行：claude-remote stop --name ${session.name}`);
+      }
+      await this.remote(config, ensureRemoteClaude(config.claude) +
+        'mkdir -p -- ' + remotePath(item.remote), false, { timeout: 600000 });
+      if (existing.some(session => session.name === item.name)) {
+        await this.sync(['resume', item.name], { timeout: 60000, capture: !this.tty });
+      } else {
+        const endpoint = config.host + ':' + (config.port != null ? config.port + ':' : '') +
+          (item.remote.startsWith('/') ? item.remote : '~/' + item.remote);
+        const args = ['create', '--name', item.name, '--label', 'claude-remote=true', '--mode', 'two-way-safe',
+          '--no-global-configuration', '--no-ignore-vcs', '--watch-polling-interval', '2'];
+        for (const pattern of config.ignores) args.push('--ignore', pattern);
+        await this.sync([...args, item.local, endpoint], { timeout: 180000, capture: !this.tty });
+      }
+      registry[item.name] = item;
+      await writeJSON(this.registryFile, registry);
+    });
+    this.log(`本地：${item.local}\n远程：${config.host}:${item.remote}\n正在完成双向同步……`);
+    await this.flush(item.name);
+    this.log('开始远程 Claude Code。退出后继续后台同步；停止请运行 claude-remote stop。');
+    let code = 1;
+    try {
+      code = (await this.remote(config, prefix + 'cd -- ' + remotePath(item.remote) +
+        ' && exec ' + shellJoin([config.claude, ...extra]), true)).code;
+    } finally {
+      try { await this.flush(item.name); }
+      catch (error) {
+        this.warn(`退出时同步未确认完成：${error.message}\n会话保留，可用 claude-remote status 检查。`);
+        if (code === 0) code = 1;
+      }
+    }
+    return code;
+  }
+
+  async stop({ all = false, name } = {}) {
+    const selected = all || name ? name : (await this.project(await this.settings())).name;
+    return withLock(this.lockFile, async () => {
+      const available = (await this.sessions()).map(session => session.name);
+      const targets = all ? available : [selected];
+      if (!targets.length || targets.some(target => !available.includes(target)))
+        throw new Error('没有找到对应同步会话；运行 claude-remote status 查看。');
+      await this.sync(['terminate', ...targets], { timeout: 30000 });
+      this.log('已停止同步，保留本地和远程文件。');
+    });
+  }
+}

package/src/installer.js

@@ -0,0 +1,81 @@
+import * as fs from 'node:fs/promises';
+import { createWriteStream, createReadStream } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execute, exists, which, withLock } from './system.js';
+
+export const VERSION = '0.18.1';
+// SHA256SUMS from the official v0.18.1 release, pinned in this package.
+export const RELEASES = {
+  'darwin-x64': ['darwin_amd64', '7d06f7d8fcfe90bc7e55cc834a2f2f20c2e0af9ea9bc35911fc4341ad56a9bbf'],
+  'darwin-arm64': ['darwin_arm64', '6f810416d9e5fc4fd5e18431146f8b3c5a2056ba5a24f76c1e66da86eb3257e2'],
+  'linux-x64': ['linux_amd64', '7735286c778cc438418209f24d03a64f3a0151c8065ef0fe079cfaf093af6f8f'],
+  'linux-arm64': ['linux_arm64', 'bcba735aebf8cbc11da9b3742118a665599ac697fa06bc5751cac8dcd540db8a']
+};
+
+export function cachedBinary(env = process.env) {
+  return path.join(env.CLAUDE_REMOTE_CACHE_DIR || path.join(os.homedir(), '.cache', 'claude-remote'),
+    `mutagen-${VERSION}-${process.platform}-${process.arch}`, 'mutagen');
+}
+
+export async function verifyChecksum(file, expected) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(file)) hash.update(chunk);
+  if (hash.digest('hex') !== expected) throw new Error('同步工具 SHA-256 校验失败，已拒绝安装。');
+}
+
+async function download(url, file) {
+  const response = await fetch(url, { signal: AbortSignal.timeout(180000) });
+  if (!response.ok || !response.body) throw new Error(`下载同步工具失败：HTTP ${response.status}`);
+  let bytes = 0;
+  const limit = new Transform({ transform(chunk, encoding, done) {
+    bytes += chunk.length;
+    done(bytes > 200 * 1024 * 1024 ? new Error('同步工具下载大小异常。') : null, chunk);
+  } });
+  await pipeline(Readable.fromWeb(response.body), limit, createWriteStream(file, { flags: 'wx', mode: 0o600 }));
+}
+
+export async function ensureMutagen({ env = process.env, forceDownload = false } = {}) {
+  if (!RELEASES[`${process.platform}-${process.arch}`]) throw new Error('此版本支持 macOS/Linux 的 x64、arm64；Windows 请在 WSL 中使用。');
+  if (env.CLAUDE_REMOTE_MUTAGEN) {
+    const binary = path.resolve(env.CLAUDE_REMOTE_MUTAGEN);
+    await execute(binary, ['version'], { capture: true, timeout: 10000, env });
+    return binary;
+  }
+  const binary = cachedBinary(env);
+  if (await exists(binary) && await exists(path.join(path.dirname(binary), 'mutagen-agents.tar.gz'))) return binary;
+  if (!forceDownload) {
+    const system = await which('mutagen', env.PATH);
+    if (system) {
+      const result = await execute(system, ['version'], { capture: true, timeout: 10000, env, check: false });
+      if (result.code === 0 && result.stdout.trim() === VERSION) return system;
+    }
+  }
+  const destination = path.dirname(binary);
+  return withLock(destination + '.lock', async () => {
+    if (await exists(binary) && await exists(path.join(destination, 'mutagen-agents.tar.gz'))) return binary;
+    const tar = await which('tar', env.PATH);
+    if (!tar) throw new Error('找不到系统 tar，无法解压同步工具。请安装 tar 后重试。');
+    const [platform, checksum] = RELEASES[`${process.platform}-${process.arch}`];
+    const archiveName = `mutagen_${platform}_v${VERSION}.tar.gz`;
+    const temporary = await fs.mkdtemp(path.join(path.dirname(destination), '.mutagen-install-'));
+    try {
+      const archive = path.join(temporary, 'download.tar.gz');
+      console.error(`正在下载同步工具 Mutagen ${VERSION}（首次使用，可能需要几分钟）……`);
+      await download(`https://github.com/mutagen-io/mutagen/releases/download/v${VERSION}/${archiveName}`, archive);
+      await verifyChecksum(archive, checksum);
+      // Extract only the two required files from the authenticated archive.
+      const unpacked = path.join(temporary, 'unpacked');
+      await fs.mkdir(unpacked);
+      await execute(tar, ['-xzf', archive, '-C', unpacked, 'mutagen', 'mutagen-agents.tar.gz'], { timeout: 60000, env });
+      await fs.chmod(path.join(unpacked, 'mutagen'), 0o755);
+      await execute(path.join(unpacked, 'mutagen'), ['version'], { capture: true, timeout: 10000, env });
+      if (await exists(destination)) await fs.rename(destination, path.join(temporary, 'old-cache'));
+      await fs.rename(unpacked, destination);
+      return binary;
+    } finally { await fs.rm(temporary, { recursive: true, force: true }); }
+  });
+}

package/src/remote-claude.js

@@ -0,0 +1,39 @@
+import { quote } from './system.js';
+
+export const remoteEnvironment = 'export PATH="$HOME/.local/bin:$PATH"; ';
+
+export function ensureRemoteClaude(command) {
+  const missing = command === 'claude' ? `
+  echo '服务器未安装 Claude Code，正在执行官方安装流程……' >&2
+  (
+    set -e
+    installer=$(mktemp "\${TMPDIR:-/tmp}/claude-remote-install.XXXXXXXX")
+    trap 'rm -f -- "$installer"' EXIT
+    if command -v curl >/dev/null 2>&1; then
+      curl -fSL --connect-timeout 20 --max-time 120 --retry 2 \\
+        --output "$installer" https://claude.ai/install.sh
+    elif command -v wget >/dev/null 2>&1; then
+      wget --timeout=120 --tries=3 --output-document="$installer" https://claude.ai/install.sh
+    else
+      echo '自动安装需要服务器提供 curl 或 wget，请先安装其中一个工具。' >&2
+      exit 127
+    fi
+    if ! bash "$installer" >&2; then
+      echo 'Claude Code 官方安装失败，请检查上述输出、网络连接和目录权限后重试。' >&2
+      exit 1
+    fi
+  )
+  hash -r
+  if ! command -v claude >/dev/null 2>&1; then
+    echo '安装器已退出，但仍找不到 Claude Code。请检查 ~/.local/bin/claude 或通过 --claude 指定绝对路径。' >&2
+    exit 127
+  fi
+  echo 'Claude Code 已安装，首次启动时请按提示完成账号认证。' >&2
+` : `
+  echo ${quote('找不到配置的 Claude 程序：' + command + '。请修正 --claude 路径，或配置 --claude claude 使用自动安装。')} >&2
+  exit 127
+`;
+  // A failed download/installer must stop before any project directory is created or synced.
+  return 'set -e\n' + remoteEnvironment + '\n' +
+    `if ! command -v ${quote(command)} >/dev/null 2>&1; then\n${missing}fi\n`;
+}

package/src/system.js

@@ -0,0 +1,83 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import lockfile from 'proper-lockfile';
+
+export const quote = value => "'" + String(value).replaceAll("'", "'\"'\"'") + "'";
+export const shellJoin = args => args.map(quote).join(' ');
+
+export async function exists(file) {
+  try { await fs.access(file); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+export async function which(name, search = process.env.PATH || '') {
+  for (const directory of search.split(path.delimiter)) {
+    const file = path.resolve(directory || '.', name);
+    try {
+      await fs.access(file, constants.X_OK);
+      if ((await fs.stat(file)).isFile()) return file;
+    } catch (error) { if (!['ENOENT', 'EACCES', 'ENOTDIR'].includes(error.code)) throw error; }
+  }
+  return null;
+}
+
+export async function readJSON(file, fallback) {
+  try { return JSON.parse(await fs.readFile(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return fallback; throw error; }
+}
+
+export async function writeJSON(file, value) {
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temp = file + '.' + randomUUID() + '.tmp';
+  try {
+    await fs.writeFile(temp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+    await fs.rename(temp, file);
+  } finally { await fs.rm(temp, { force: true }); }
+}
+
+export function execute(command, args = [], { capture = false, timeout = 0, check = true, env = process.env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit', env });
+    let stdout = '', stderr = '', timedOut = false, overflow = false, killTimer;
+    const interrupt = () => child.kill('SIGINT');
+    process.on('SIGINT', interrupt);
+    const timer = timeout ? setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), 2000);
+    }, timeout) : null;
+    const cleanup = () => {
+      clearTimeout(timer); clearTimeout(killTimer);
+      process.off('SIGINT', interrupt);
+    };
+    if (capture) {
+      child.stdout.setEncoding('utf8'); child.stderr.setEncoding('utf8');
+      child.stdout.on('data', chunk => {
+        stdout += chunk;
+        if (stdout.length > 32 * 1024 * 1024) { overflow = true; child.kill('SIGKILL'); }
+      });
+      child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-65536); });
+    }
+    child.once('error', error => { cleanup(); reject(new Error(`无法执行 ${command}：${error.message}`)); });
+    child.once('close', (status, signal) => {
+      cleanup();
+      const code = status ?? (signal === 'SIGINT' ? 130 : 1);
+      if (timedOut) reject(new Error(`${path.basename(command)} 执行超时；请检查连接或同步状态。`));
+      else if (overflow) reject(new Error('命令输出过大，请使用 claude-remote status 检查。'));
+      else if (check && code) reject(new Error(`${path.basename(command)} 执行失败（${code}）${stderr ? '：' + stderr.trim() : ''}`));
+      else resolve({ code, stdout, stderr });
+    });
+  });
+}
+
+// Heartbeat locks survive long downloads and recover after an interrupted process.
+export async function withLock(directory, callback) {
+  await fs.mkdir(path.dirname(directory), { recursive: true, mode: 0o700 });
+  const release = await lockfile.lock(directory, { realpath: false, stale: 30000, update: 10000,
+    retries: { retries: 240, minTimeout: 1000, maxTimeout: 1000 } });
+  try { return await callback(); }
+  finally { await release(); }
+}