opencode-idea 0.1.4 → 0.1.5

package/src/remote/hosts.js

@@ -0,0 +1,269 @@
+// 远程服务器的三级来源：IDE → 项目 `.opencode/remote-shell/hosts.json` → 全局 `~/.config/remote-shell/hosts.json`。
+//
+// 合并规则（同名以高优先级为准）：
+//
+//   global（最低） → project → IDE（最高）
+//
+// 这个文件只做**纯数据**的事：读文件、校验形状、合并。调 IDE 取凭据在 `plugin.js`
+// 里（那里才拿得到端口和项目路径），SSH 连接在 `ssh.js` 里。
+
+import {existsSync, readFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+
+/** 全局配置。保留 remote-shell 的旧路径，用户的 hosts.json 不用搬。 */
+export const GLOBAL_HOSTS_PATH = join(homedir(), '.config', 'remote-shell', 'hosts.json');
+
+/** 项目级配置：与全局同名同格式，跟着仓库走。 */
+export function projectHostsPath(projectPath) {
+    return join(projectPath, '.opencode', 'remote-shell', 'hosts.json');
+}
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   alias?: string,
+ *   host?: string,
+ *   port?: number,
+ *   username?: string,
+ *   authType?: string,
+ *   password?: string,
+ *   passphrase?: string,
+ *   privateKeyPath?: string,
+ *   deployments: Array<{ name: string, localPath: string, deployPath: string }>,
+ *   source: 'ide' | 'project' | 'global',
+ * }} RemoteServer
+ */
+
+/**
+ * 读一个 hosts.json，返回服务器列表；文件不存在 / 内容坏 / 字段不全时返回空数组。
+ *
+ * `source` 由调用方给：同一个文件在"项目级"和"全局"两个位置读时，条目要能区分。
+ *
+ * @param {string} path
+ * @param {'ide' | 'project' | 'global'} source
+ * @returns {RemoteServer[]}
+ */
+export function readHostsFile(path, source) {
+    if (!existsSync(path)) return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+        // 配置坏了不该让整个 remote_exec 不可用；跳过这一层，其它层照常合并。
+        return [];
+    }
+    const hosts = parsed?.hosts;
+    if (!hosts || typeof hosts !== 'object') return [];
+
+    const servers = [];
+    for (const [name, entry] of Object.entries(hosts)) {
+        const server = toServer(name, entry, source);
+        if (server) servers.push(server);
+    }
+    return servers;
+}
+
+/**
+ * 一条 hosts.json 条目 → RemoteServer；缺 host 或 username 的直接丢掉。
+ *
+ * @param {string} name
+ * @param {unknown} entry
+ * @param {'ide' | 'project' | 'global'} source
+ * @returns {RemoteServer | undefined}
+ */
+function toServer(name, entry, source) {
+    if (!entry || typeof entry !== 'object') return undefined;
+    const record = /** @type {Record<string, unknown>} */ (entry);
+    const host = typeof record.host === 'string' ? record.host.trim() : '';
+    const username = typeof record.username === 'string' ? record.username.trim() : '';
+    const deployments = parseDeployments(record.deployments);
+    // 允许"只补 mapping"的条目：没有 host、但带了 deployments 时也算一条补丁，合并时由
+    // 低优先级层补上连接信息。没有 host 又没有 mapping 的条目没有任何用途（单独一个 username
+    // 既连不上也补不了东西），直接丢掉。三层都只有补丁的条目会在 finalize 时再过滤一次。
+    if (!host && deployments.length === 0) return undefined;
+
+    /** @type {RemoteServer} */
+    const server = {name, source, deployments};
+    const alias = stringOrUndefined(record.alias);
+    if (alias && alias !== name) server.alias = alias;
+    if (host) server.host = host;
+    if (username) server.username = username;
+    if (typeof record.port === 'number' && Number.isFinite(record.port) && record.port > 0) {
+        server.port = record.port;
+    }
+    const authType = stringOrUndefined(record.authType);
+    if (authType) server.authType = authType;
+    const password = stringOrUndefined(record.password);
+    if (password) server.password = password;
+    const passphrase = stringOrUndefined(record.passphrase);
+    if (passphrase) server.passphrase = passphrase;
+    const privateKeyPath = stringOrUndefined(record.privateKeyPath);
+    if (privateKeyPath) server.privateKeyPath = privateKeyPath;
+    return server;
+}
+
+/** @param {unknown} value */
+function stringOrUndefined(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+
+/**
+ * 解析一个 server 上的路径映射。缺 name / localPath / deployPath 的条目直接丢掉 ——
+ * 少了任何一头都传不了。
+ *
+ * @param {unknown} raw
+ * @returns {Array<{ name: string, localPath: string, deployPath: string }>}
+ */
+function parseDeployments(raw) {
+    if (!Array.isArray(raw)) return [];
+    return raw.flatMap((entry) => {
+        if (!entry || typeof entry !== 'object') return [];
+        const record = /** @type {Record<string, unknown>} */ (entry);
+        const name = typeof record.name === 'string' ? record.name : '';
+        const localPath = typeof record.localPath === 'string' ? record.localPath : '';
+        const deployPath = typeof record.deployPath === 'string' ? record.deployPath : '';
+        if (!name || !localPath || !deployPath) return [];
+        return [{name, localPath, deployPath}];
+    });
+}
+
+/**
+ * 把合并后的 server 列表摊平成 deployment 表（按 name 全局唯一）。
+ *
+ * `server` 挂在每条 mapping 上：上传 / 下载既要知道两端目录，也要知道连哪台机器。
+ *
+ * @param {ReadonlyArray<RemoteServer>} servers
+ * @returns {Array<{ name: string, localPath: string, deployPath: string, server: RemoteServer }>}
+ */
+export function collectDeployments(servers) {
+    const byName = new Map();
+    for (const server of servers) {
+        for (const deployment of server.deployments ?? []) {
+            byName.set(deployment.name, {...deployment, server});
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * 按 name 合并多层服务器。**后传的层覆盖先传的层**。
+ *
+ * 调用方按 `[global, project, ide]` 的顺序传，就是"全局 < 项目 < IDE"。
+ *
+ * @param {ReadonlyArray<ReadonlyArray<RemoteServer>>} layers
+ * @returns {RemoteServer[]}
+ */
+export function mergeServers(layers) {
+    const byName = new Map();
+    for (const layer of layers) {
+        for (const server of layer) {
+            const existing = byName.get(server.name);
+            byName.set(server.name, existing ? mergeServer(existing, server) : server);
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * 两层的同一条 server 合并：高优先级的字段覆盖，没提供的保留。
+ *
+ * **不是整条替换**，理由是常见的配置方式：项目级只想补一条 deployment，不该被迫把
+ * 密码再抄一遍；反过来 IDE 里改了 host 也不该把项目级补的 mapping 冲掉。
+ *
+ * 凭据字段例外：只要高优先级层给了 `authType`，就以它的凭据为准（KEY_PAIR 必须能清掉
+ * 低优先级层的 password，否则会带着一个不该用的密码去连接）。
+ *
+ * @param {RemoteServer} base 低优先级
+ * @param {RemoteServer} override 高优先级
+ * @returns {RemoteServer}
+ */
+function mergeServer(base, override) {
+    /** @type {RemoteServer} */
+    const merged = {...base};
+    for (const [key, value] of Object.entries(override)) {
+        if (value === undefined) continue;
+        if (key === 'deployments' || key === 'authType') continue;
+        // @ts-expect-error 键来自同一个结构
+        merged[key] = value;
+    }
+
+    if (override.authType) {
+        merged.authType = override.authType;
+        merged.password = override.password;
+        merged.passphrase = override.passphrase;
+        merged.privateKeyPath = override.privateKeyPath;
+    }
+
+    merged.deployments = mergeDeployments(base.deployments ?? [], override.deployments ?? []);
+    return merged;
+}
+
+/**
+ * deployment 按 name 合并；高优先级层没配任何 mapping 时保留低优先级的。
+ *
+ * @param {Array<{ name: string, localPath: string, deployPath: string }>} base
+ * @param {Array<{ name: string, localPath: string, deployPath: string }>} override
+ */
+function mergeDeployments(base, override) {
+    if (override.length === 0) return base;
+    const byName = new Map(base.map((deployment) => [deployment.name, deployment]));
+    for (const deployment of override) byName.set(deployment.name, deployment);
+    return [...byName.values()];
+}
+
+/**
+ * 精确按名字找。**不做模糊匹配**：猜错了比列出来更糟，让模型看着全量列表自己选。
+ *
+ * @param {ReadonlyArray<RemoteServer>} servers
+ * @param {string} name
+ */
+export function findServer(servers, name) {
+    // 旧 remote-shell 的 `findHost` 优先按 alias 匹配；这里保持一致，现有配置里的
+    // `"alias": "远程开发机"` 可以继续用。name 命中优先于 alias。
+    return servers.find((server) => server.name === name)
+        ?? servers.find((server) => server.alias === name);
+}
+
+/**
+ * 找不到 deployment 时给模型的文本：列出全部候选（名字 / 两端目录 / 所属服务器）。
+ *
+ * @param {ReturnType<typeof collectDeployments>} deployments
+ * @param {string} wanted
+ */
+export function deploymentNotFoundText(deployments, wanted) {
+    if (deployments.length === 0) {
+        return `没有名为 "${wanted}" 的 deployment，当前也没有任何路径映射。` +
+            `在 IDE 的 Deployment 里配置，或在 hosts.json 的 host 条目下加 deployments。`;
+    }
+    const lines = deployments.map((deployment) =>
+        `- ${deployment.name}  ${deployment.localPath} ↔ ${deployment.server.name}:${deployment.deployPath}`);
+    return [
+        `没有名为 "${wanted}" 的 deployment。当前全部可用：`,
+        '',
+        ...lines,
+        '',
+        '如果指的是其中一条，用它的名字重新调用。',
+    ].join('\n');
+}
+
+/**
+ * 找不到服务器时给模型的文本：列出全部候选（名字 / 地址 / 用户 / 来源），绝不带凭据。
+ *
+ * @param {ReadonlyArray<RemoteServer>} servers
+ * @param {string} wanted
+ */
+export function serverNotFoundText(servers, wanted) {
+    const lines = servers.map((server) => {
+        const source = server.source === 'ide' ? 'IDE' : server.source === 'project' ? '项目' : '全局';
+        const label = server.alias ? `${server.name} (${server.alias})` : server.name;
+        return `- ${label}  ${server.host}:${server.port}  ${server.username}  [${source}]`;
+    });
+    return [
+        `没有名为 "${wanted}" 的服务器。当前全部可用（IDE → 项目 → 全局，同名以高优先级为准）：`,
+        '',
+        ...lines,
+        '',
+        '如果指的是其中某一台，用它的名字重新调用。',
+    ].join('\n');
+}

package/src/remote/hosts.test.js

@@ -0,0 +1,171 @@
+// 三级合并的纯函数测试：合并顺序、来源标记、坏配置容错。
+
+import {mkdirSync, mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+
+import {afterAll, describe, expect, it} from 'vitest';
+
+import {collectDeployments, deploymentNotFoundText, findServer, mergeServers, readHostsFile, serverNotFoundText} from './hosts.js';
+
+const workDir = mkdtempSync(join(tmpdir(), 'remote-hosts-'));
+afterAll(() => rmSync(workDir, {recursive: true, force: true}));
+
+/** @param {string} name @param {string} host @param {'ide'|'project'|'global'} source */
+const server = (name, host, source) => ({name, host, port: 22, username: 'u', source});
+
+describe('mergeServers', () => {
+    it('同名时后传的层覆盖先传的（global < project < ide）', () => {
+        const merged = mergeServers([
+            [server('a', 'global-host', 'global'), server('g', 'g-host', 'global')],
+            [server('b', 'project-host', 'project')],
+            [server('a', 'ide-host', 'ide')],
+        ]);
+        expect(merged.map((entry) => `${entry.name}:${entry.host}:${entry.source}`)).toEqual([
+            'a:ide-host:ide',
+            'b:project-host:project',
+            'g:g-host:global',
+        ]);
+    });
+
+    it('空层不丢其它层', () => {
+        expect(mergeServers([[], [server('a', 'h', 'project')], []])).toHaveLength(1);
+    });
+
+    it('项目级只补 deployment 时沿用低优先级的连接信息', () => {
+        const merged = mergeServers([
+            [{name: 'mbp', host: 'h', port: 22, username: 'u', password: 'p', deployments: [], source: 'global'}],
+            [{name: 'mbp', deployments: [{name: 'app', localPath: '/l', deployPath: '/r'}], source: 'project'}],
+        ]);
+        expect(merged).toHaveLength(1);
+        expect(merged[0].host).toBe('h');
+        expect(merged[0].password).toBe('p');
+        expect(merged[0].deployments).toEqual([{name: 'app', localPath: '/l', deployPath: '/r'}]);
+        // 来源标最高优先级那层
+        expect(merged[0].source).toBe('project');
+    });
+
+    it('高优先级层给了 authType 时以它的凭据为准（KEY_PAIR 能清掉旧的 password）', () => {
+        const merged = mergeServers([
+            [{name: 'a', host: 'h', username: 'u', password: 'p', source: 'global'}],
+            [{name: 'a', authType: 'KEY_PAIR', privateKeyPath: '/k', source: 'ide'}],
+        ]);
+        expect(merged[0].password).toBeUndefined();
+        expect(merged[0].privateKeyPath).toBe('/k');
+    });
+});
+
+describe('findServer', () => {
+    it('按 alias 也能找到（兼容旧 remote-shell 配置）', () => {
+        const servers = [{
+            name: 'remote-dev',
+            alias: '远程开发机',
+            host: 'h',
+            port: 22,
+            username: 'u',
+            source: 'global',
+        }];
+        expect(findServer(servers, '远程开发机')?.name).toBe('remote-dev');
+        expect(findServer(servers, 'remote-dev')?.name).toBe('remote-dev');
+    });
+
+    it('只做精确匹配，不猜', () => {
+        const servers = [server('deploy1', 'h', 'ide')];
+        expect(findServer(servers, 'deploy1')?.name).toBe('deploy1');
+        expect(findServer(servers, 'dev1')).toBeUndefined();
+    });
+});
+
+describe('serverNotFoundText', () => {
+    it('列出全部候选并标出来源', () => {
+        const text = serverNotFoundText(
+            [server('deploy1', '10.0.0.5', 'ide'), server('5090', '10.0.0.9', 'global')],
+            'dev1',
+        );
+        expect(text).toContain('没有名为 "dev1" 的服务器');
+        expect(text).toContain('- deploy1  10.0.0.5:22  u  [IDE]');
+        expect(text).toContain('- 5090  10.0.0.9:22  u  [全局]');
+    });
+});
+
+describe('readHostsFile', () => {
+    it('读 hosts 并标来源', () => {
+        const path = join(workDir, 'good.json');
+        writeFileSync(path, JSON.stringify({
+            hosts: {dev: {host: '10.0.0.1', port: 2222, username: 'root', password: 'p'}},
+        }));
+        const servers = readHostsFile(path, 'project');
+        expect(servers).toEqual([
+            {
+                name: 'dev',
+                host: '10.0.0.1',
+                port: 2222,
+                username: 'root',
+                password: 'p',
+                deployments: [],
+                source: 'project',
+            },
+        ]);
+    });
+
+    it('文件不存在 / JSON 坏 / 缺 host 时返回空数组，不抛', () => {
+        const missing = join(workDir, 'missing.json');
+        expect(readHostsFile(missing, 'global')).toEqual([]);
+
+        const broken = join(workDir, 'broken.json');
+        writeFileSync(broken, '{not json');
+        expect(readHostsFile(broken, 'global')).toEqual([]);
+
+        const noHost = join(workDir, 'no-host.json');
+        writeFileSync(noHost, JSON.stringify({hosts: {bad: {username: 'u'}}}));
+        expect(readHostsFile(noHost, 'global')).toEqual([]);
+    });
+});
+
+describe('deployments', () => {
+    it('从 host 条目里解析路径映射，缺一头的丢掉', () => {
+        const path = join(workDir, 'with-deployments.json');
+        writeFileSync(path, JSON.stringify({
+            hosts: {
+                dev: {
+                    host: '10.0.0.1',
+                    username: 'u',
+                    deployments: [
+                        {name: 'app', localPath: '/local/app', deployPath: '/srv/app'},
+                        {name: 'broken', localPath: '/local/x'},
+                    ],
+                },
+            },
+        }));
+        expect(readHostsFile(path, 'project')[0].deployments).toEqual([
+            {name: 'app', localPath: '/local/app', deployPath: '/srv/app'},
+        ]);
+    });
+
+    it('collectDeployments 摊平成全局表，并挂上所属 server', () => {
+        const servers = [
+            {...server('a', 'h1', 'global'), deployments: [{name: 'x', localPath: '/l', deployPath: '/r'}]},
+            {...server('b', 'h2', 'ide'), deployments: [{name: 'y', localPath: '/l2', deployPath: '/r2'}]},
+        ];
+        const deployments = collectDeployments(servers);
+        expect(deployments.map((entry) => `${entry.name}:${entry.server.name}`)).toEqual(['x:a', 'y:b']);
+    });
+
+    it('找不到 deployment 时列出全部候选', () => {
+        const deployments = [{name: 'app', localPath: '/l', deployPath: '/r', server: server('a', 'h', 'ide')}];
+        expect(deploymentNotFoundText(deployments, 'api')).toContain('app  /l ↔ a:/r');
+    });
+});
+
+describe('只补 mapping 的条目', () => {
+    it('没有 host / username 但带了 deployments 时保留为补丁', () => {
+        const path = join(workDir, 'patch-only.json');
+        writeFileSync(path, JSON.stringify({
+            hosts: {mbp: {deployments: [{name: 'app', localPath: '/l', deployPath: '/r'}]}},
+        }));
+        const servers = readHostsFile(path, 'project');
+        expect(servers).toHaveLength(1);
+        expect(servers[0].host).toBeUndefined();
+        expect(servers[0].deployments).toHaveLength(1);
+    });
+});

package/src/remote/persist.js

@@ -0,0 +1,106 @@
+// `/persist-remote-config`：把 IDE 里配置的 server 与 deployment 写进项目配置。
+//
+// 位置固定为 `<项目>/.opencode/remote-shell/hosts.json` —— 和 `hosts.js` 读的是同一个文件，
+// 所以写完立刻能被 remote_list_servers / remote_exec / remote_upload 看到（项目级优先于全局）。
+//
+// 合并规则：IDE 有的 server 整体覆盖，IDE 没有的原样保留。不留备份文件 —— 项目里的配置由 git 管。
+// 凭据照写（用户自己决定这个文件要不要进 git，工具不替用户做这个判断）。
+
+import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+
+/** 项目级配置目录。 */
+export function remoteConfigDir(projectPath) {
+    return join(projectPath, '.opencode', 'remote-shell');
+}
+
+/** 项目级配置文件。 */
+export function remoteConfigPath(projectPath) {
+    return join(remoteConfigDir(projectPath), 'hosts.json');
+}
+
+/**
+ * 一条 `RemoteServer` → hosts.json 里的条目。
+ *
+ * 只写这个文件认识（且确实有值）的字段：`authType` 决定 `password` / `privateKeyPath` 谁有意义，
+ * 空值不写出来，免得读的时候被当成"显式设成空"。
+ *
+ * @param {import('./hosts.js').RemoteServer} server
+ */
+export function toHostEntry(server) {
+    /** @type {Record<string, unknown>} */
+    const entry = {
+        // alias 默认和 server 名一致：调用时用哪个都行，想换名字直接改这个字段，
+        // map 的 key 保持和 IDE 里一致（下次持久化也能正确覆盖）。
+        alias: server.alias ?? server.name,
+        host: server.host,
+        port: server.port ?? 22,
+        username: server.username,
+        authType: server.authType,
+        deployments: (server.deployments ?? []).map((deployment) => ({
+            name: deployment.name,
+            localPath: deployment.localPath,
+            deployPath: deployment.deployPath,
+        })),
+    };
+    if (server.password) entry.password = server.password;
+    if (server.passphrase) entry.passphrase = server.passphrase;
+    if (server.privateKeyPath) entry.privateKeyPath = server.privateKeyPath;
+    return entry;
+}
+
+/**
+ * 把 IDE 的服务器写进项目配置。
+ *
+ * @param {{
+ *   projectPath: string,
+ *   servers: ReadonlyArray<import('./hosts.js').RemoteServer>,
+ * }} options
+ * @returns {{
+ *   path: string,
+ *   added: number,
+ *   updated: number,
+ *   kept: number,
+ *   total: number,
+ *   deployments: number,
+ * }}
+ */
+export function persistRemoteConfig({projectPath, servers}) {
+    const dir = remoteConfigDir(projectPath);
+    const file = remoteConfigPath(projectPath);
+    mkdirSync(dir, {recursive: true});
+
+    /** @type {Record<string, unknown>} */
+    let existing = {};
+    if (existsSync(file)) {
+        try {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            existing = parsed?.hosts && typeof parsed.hosts === 'object' ? parsed.hosts : {};
+        } catch {
+            // 文件坏了也要能覆盖：当成空的，重新写一份合法的。
+            existing = {};
+        }
+    }
+
+    const next = {...existing};
+    let added = 0;
+    let updated = 0;
+    for (const server of servers) {
+        if (next[server.name]) updated += 1;
+        else added += 1;
+        next[server.name] = toHostEntry(server);
+    }
+    const ideNames = new Set(servers.map((server) => server.name));
+    const kept = Object.keys(existing).filter((name) => !ideNames.has(name)).length;
+
+    writeFileSync(file, `${JSON.stringify({hosts: next}, null, 2)}\n`, 'utf8');
+
+    return {
+        path: file,
+        added,
+        updated,
+        kept,
+        total: Object.keys(next).length,
+        deployments: servers.reduce((sum, server) => sum + (server.deployments?.length ?? 0), 0),
+    };
+}

package/src/remote/persist.test.js

@@ -0,0 +1,100 @@
+// `/persist-remote-config` 的纯函数测试：新建、覆盖、保留、备份。
+
+import {existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+
+import {afterAll, describe, expect, it} from 'vitest';
+
+import {persistRemoteConfig, remoteConfigPath, toHostEntry} from './persist.js';
+
+const workDir = mkdtempSync(join(tmpdir(), 'persist-'));
+afterAll(() => rmSync(workDir, {recursive: true, force: true}));
+
+const project = () => mkdtempSync(join(workDir, 'project-'));
+
+const server = (name, overrides = {}) => ({
+    name,
+    host: '10.0.0.1',
+    port: 22,
+    username: 'u',
+    authType: 'PASSWORD',
+    password: 'p',
+    deployments: [{name: 'app', localPath: '/local/app', deployPath: '/srv/app'}],
+    source: 'ide',
+    ...overrides,
+});
+
+describe('toHostEntry', () => {
+    it('写凭据、mapping，不写空字段', () => {
+        expect(toHostEntry(server('a'))).toEqual({
+            alias: 'a',
+            host: '10.0.0.1',
+            port: 22,
+            username: 'u',
+            authType: 'PASSWORD',
+            password: 'p',
+            deployments: [{name: 'app', localPath: '/local/app', deployPath: '/srv/app'}],
+        });
+        expect(toHostEntry(server('b', {password: undefined, privateKeyPath: '/k', authType: 'KEY_PAIR'})))
+            .not.toHaveProperty('password');
+    });
+});
+
+describe('persistRemoteConfig', () => {
+    it('项目里没有文件时新建，并写入凭据与 mapping', () => {
+        const projectPath = project();
+        const result = persistRemoteConfig({projectPath, servers: [server('a')]});
+
+        expect(result.added).toBe(1);
+        expect(result.updated).toBe(0);
+        expect(result.kept).toBe(0);
+        expect(result.deployments).toBe(1);
+
+        const json = JSON.parse(readFileSync(remoteConfigPath(projectPath), 'utf8'));
+        expect(json.hosts.a.alias).toBe('a');
+        expect(json.hosts.a.password).toBe('p');
+        expect(json.hosts.a.deployments).toEqual([
+            {name: 'app', localPath: '/local/app', deployPath: '/srv/app'},
+        ]);
+    });
+
+    it('同名覆盖、项目独有保留', () => {
+        const projectPath = project();
+        const file = remoteConfigPath(projectPath);
+        mkdirSync(join(projectPath, '.opencode', 'remote-shell'), {recursive: true});
+        writeFileSync(file, JSON.stringify({
+            hosts: {
+                a: {host: 'old-host', username: 'old-user'},
+                manual: {host: 'manual-host', username: 'u'},
+            },
+        }));
+
+        const result = persistRemoteConfig({projectPath, servers: [server('a', {host: 'new-host'})]});
+
+        expect(result.added).toBe(0);
+        expect(result.updated).toBe(1);
+        expect(result.kept).toBe(1);
+        expect(result.total).toBe(2);
+
+        const json = JSON.parse(readFileSync(file, 'utf8'));
+        expect(json.hosts.a.host).toBe('new-host');
+        expect(json.hosts.a.alias).toBe('a');
+        expect(json.hosts.a.password).toBe('p');
+        // IDE 里没有的那条原样保留
+        expect(json.hosts.manual.host).toBe('manual-host');
+    });
+
+    it('旧文件坏掉时仍能写入一份合法的配置', () => {
+        const projectPath = project();
+        const file = remoteConfigPath(projectPath);
+        mkdirSync(join(projectPath, '.opencode', 'remote-shell'), {recursive: true});
+        writeFileSync(file, '{not json');
+
+        const result = persistRemoteConfig({projectPath, servers: [server('a')]});
+
+        expect(result.added).toBe(1);
+        expect(existsSync(`${file}.bak`)).toBe(false);
+        expect(JSON.parse(readFileSync(file, 'utf8')).hosts.a.host).toBe('10.0.0.1');
+    });
+});