paintress 0.2.3 → 0.3.1

package/README.md

@@ -84,8 +84,10 @@ Canvas navigation: wheel zooms at the pointer, space / middle button / empty are
 | Claude Desktop | `~/.config/Claude/claude_desktop_config.json` | `mcpServers` |
 | Cursor | `~/.cursor/mcp.json` | `mcpServers` |
 | VS Code | `~/.config/Code/User/mcp.json` | `servers` (with `"type": "stdio"`) |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` |
 | Codex | `~/.codex/config.toml` | `[mcp_servers.paintress]` |
 | pi | `~/.pi/agent/mcp.json` | `mcpServers` |
+| OpenCode | `~/.config/opencode/opencode.json` | `mcp.servers` (current) or `mcp` (older; `command` is an array) |
 
 ```bash
 paintress mcp-config cursor   # print the exact snippet instead of editing files
@@ -126,9 +128,15 @@ You are an agent asked to install paintress on this machine. Work through the st
 Rules:
 
 - **Any hit means reuse.** Do not install again; go to step 2.
-- Report the resolved path and version (`paintress ping` prints the daemon version when the viewer runs; `npm ls -g --depth=0 paintress` prints the package version).
+- Report the resolved path and version: `paintress --version` prints the package version (or `npm ls -g --depth=0 paintress`).
 - Only when every check is empty do you install (step 1).
 
+If the install succeeded but `command -v paintress` still finds nothing (some version managers need a new shell), call it by full path — do not install a second copy:
+
+```bash
+"$(npm prefix -g)/bin/paintress" doctor
+```
+
 ### 1. Install (only if step 0 found nothing)
 
 ```bash
@@ -152,7 +160,9 @@ paintress install --dry-run         # preview the writes
 paintress install <client-id>       # write only the client you are running in
 ```
 
-Client ids: `claude`, `cursor`, `vscode`, `codex`, `pi`. Use `paintress install` without arguments to cover every detected client.
+Client ids: `claude`, `cursor`, `vscode`, `windsurf`, `codex`, `pi`, `opencode`. Use `paintress install` without arguments to cover every detected client.
+
+OpenCode has two config layouts in the wild. `install` follows whatever the existing file already uses and falls back to the current `mcp.servers` shape for a new file; force it with `--opencode-layout legacy` or `--opencode-layout v2`.
 
 What the write does:
 
@@ -162,14 +172,23 @@ What the write does:
 - is idempotent: an identical entry reports `noop` and nothing is written;
 - uses the bare command `paintress` when it resolves on PATH, otherwise the absolute path of the binary.
 
-If the agent you run in is not in that list, print the closest snippet and adapt it:
+### If your client is not in that list
+
+The entry is small and nearly the same everywhere, so adapt it by hand:
+
+1. Find where the client keeps its MCP servers — its own docs, an `/mcp` command, or a "configure MCP servers" menu item.
+2. Match the shape. Most clients use a `mcpServers` object holding `command` + `args`; VS Code uses `servers` with `"type": "stdio"`; OpenCode puts a single `command` **array** under `mcp.servers` (older builds: under `mcp`) with `"type": "local"`; Codex uses a TOML table.
+3. Print the closest snippet and edit it:
 
 ```bash
-paintress mcp-config cursor   # JSON with mcpServers
-paintress mcp-config vscode   # JSON with servers + type: stdio
-paintress mcp-config codex    # TOML table
+paintress mcp-config cursor     # JSON with mcpServers
+paintress mcp-config vscode     # JSON with servers + type: stdio
+paintress mcp-config opencode   # JSON with mcp.servers + command array
+paintress mcp-config codex      # TOML table
 ```
 
+To make a client first-class (so `doctor` and `install` cover it), add one spec to `src/integrations/clients.ts` — `id`, `label`, `format`, `rootPath`, optional `typeValue` / `commandForm` / `extraFields`, and `configPath(home, platform, env)` — plus one test in `test/integrations.spec.ts`. No other file needs to change.
+
 ### 3. Install the skill (recommended)
 
 ```bash

package/README.zh-CN.md

@@ -84,8 +84,10 @@ paintress watch demo ./demo
 | Claude Desktop | `~/.config/Claude/claude_desktop_config.json` | `mcpServers` |
 | Cursor | `~/.cursor/mcp.json` | `mcpServers` |
 | VS Code | `~/.config/Code/User/mcp.json` | `servers`（条目需 `"type": "stdio"`） |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` |
 | Codex | `~/.codex/config.toml` | `[mcp_servers.paintress]` |
 | pi | `~/.pi/agent/mcp.json` | `mcpServers` |
+| OpenCode | `~/.config/opencode/opencode.json` | `mcp.servers`（当前版）或 `mcp`（旧版；`command` 是数组） |
 
 ```bash
 paintress mcp-config cursor   # 只打印片段，不改文件
@@ -126,9 +128,15 @@ MIT
 规则：
 
 - **命中任意一项就复用**，不要重装，直接进入第 2 步。
-- 向用户报告解析到的路径与版本（查看器运行时 `paintress ping` 会打印版本；包版本用 `npm ls -g --depth=0 paintress`）。
+- 向用户报告解析到的路径与版本：`paintress --version` 打印包版本（或用 `npm ls -g --depth=0 paintress`）。
 - 只有在全部检查都为空时，才执行第 1 步。
 
+如果安装成功但 `command -v paintress` 仍然找不到（某些版本管理器需要新开 shell），用完整路径调用，**不要因此再装一份**：
+
+```bash
+"$(npm prefix -g)/bin/paintress" doctor
+```
+
 ### 1. 安装（仅在检测全空时）
 
 ```bash
@@ -152,7 +160,9 @@ paintress install --dry-run         # 预览将要写入的内容
 paintress install <client-id>       # 只写当前所在的客户端
 ```
 
-客户端 id：`claude`、`cursor`、`vscode`、`codex`、`pi`。不带参数执行 `paintress install` 会覆盖所有检测到的客户端。
+客户端 id：`claude`、`cursor`、`vscode`、`windsurf`、`codex`、`pi`、`opencode`。不带参数执行 `paintress install` 会覆盖所有检测到的客户端。
+
+OpenCode 现在有两套配置布局：`install` 会跟随文件里既有的布局，新文件按官方当前的 `mcp.servers`；需要强制时用 `--opencode-layout legacy` 或 `--opencode-layout v2`。
 
 写入行为：
 
@@ -162,14 +172,23 @@ paintress install <client-id>       # 只写当前所在的客户端
 - 幂等：条目已一致时返回 `noop`，不写磁盘；
 - 当 `paintress` 能在 PATH 上解析时写裸命令，否则写可执行文件的绝对路径。
 
-如果当前 agent 不在列表里，打印最接近的片段再自行适配：
+### 如果当前 agent 不在列表里
+
+条目很小，各家格式几乎一致，直接照抄改写即可：
+
+1. 先找到该客户端放 MCP server 的位置——查它自己的文档、`/mcp` 命令，或「配置 MCP 服务器」菜单项。
+2. 对照格式：多数是 `mcpServers` 对象，里面 `command` + `args`；VS Code 是 `servers` 加 `"type": "stdio"`；OpenCode 的 `command` 是**数组**，放在 `mcp.servers` 下（旧版放 `mcp` 下）并带 `"type": "local"`；Codex 是 TOML 表。
+3. 打印最接近的片段再改：
 
 ```bash
-paintress mcp-config cursor   # JSON，顶层 mcpServers
-paintress mcp-config vscode   # JSON，顶层 servers + type: stdio
-paintress mcp-config codex    # TOML 表
+paintress mcp-config cursor     # JSON，顶层 mcpServers
+paintress mcp-config vscode     # JSON，顶层 servers + type: stdio
+paintress mcp-config opencode   # JSON，mcp.servers + command 数组
+paintress mcp-config codex      # TOML 表
 ```
 
+想让某个客户端成为内置支持（`doctor`、`install` 都能覆盖），只需在 `src/integrations/clients.ts` 里加一条配置：`id`、`label`、`format`、`rootPath`，以及可选的 `typeValue` / `commandForm` / `extraFields` 和 `configPath(home, platform, env)`，再在 `test/integrations.spec.ts` 加一个测试。其他文件都不用动。
+
 ### 3. 安装 skill（建议）
 
 ```bash

package/dist/cli.js

@@ -859,8 +859,7 @@ const CLIENTS = [
 		id: "claude",
 		label: "Claude Desktop",
 		format: "json",
-		rootKey: "mcpServers",
-		needsType: false,
+		rootPath: ["mcpServers"],
 		configPath: (home, platform, env) => {
 			if (platform === "darwin") return `${posixHome(home)}/Library/Application Support/Claude/claude_desktop_config.json`;
 			if (platform === "win32") return `${env["APPDATA"] ?? posixHome(home)}/Claude/claude_desktop_config.json`;
@@ -871,37 +870,54 @@ const CLIENTS = [
 		id: "cursor",
 		label: "Cursor",
 		format: "json",
-		rootKey: "mcpServers",
-		needsType: false,
+		rootPath: ["mcpServers"],
 		configPath: (home) => `${posixHome(home)}/.cursor/mcp.json`
 	},
 	{
 		id: "vscode",
 		label: "VS Code",
 		format: "json",
-		rootKey: "servers",
-		needsType: true,
+		rootPath: ["servers"],
+		typeValue: "stdio",
 		configPath: (home, platform, env) => {
 			if (platform === "darwin") return `${posixHome(home)}/Library/Application Support/Code/User/mcp.json`;
 			if (platform === "win32") return `${env["APPDATA"] ?? posixHome(home)}/Code/User/mcp.json`;
 			return `${posixHome(home)}/.config/Code/User/mcp.json`;
 		}
 	},
+	{
+		id: "windsurf",
+		label: "Windsurf",
+		format: "json",
+		rootPath: ["mcpServers"],
+		configPath: (home, platform, env) => {
+			return `${platform === "win32" ? env["USERPROFILE"] ?? posixHome(home) : posixHome(home)}/.codeium/windsurf/mcp_config.json`;
+		}
+	},
 	{
 		id: "codex",
 		label: "Codex",
 		format: "toml",
-		rootKey: "mcp_servers",
-		needsType: false,
+		rootPath: ["mcp_servers"],
 		configPath: (home) => `${posixHome(home)}/.codex/config.toml`
 	},
 	{
 		id: "pi",
 		label: "pi",
 		format: "json",
-		rootKey: "mcpServers",
-		needsType: false,
+		rootPath: ["mcpServers"],
 		configPath: (home) => `${posixHome(home)}/.pi/agent/mcp.json`
+	},
+	{
+		id: "opencode",
+		label: "OpenCode",
+		format: "json",
+		rootPath: ["mcp", "servers"],
+		typeValue: "local",
+		commandForm: "command-array",
+		configPath: (home, _platform, env) => {
+			return `${env["XDG_CONFIG_HOME"] ?? `${posixHome(home)}/.config`}/opencode/opencode.json`;
+		}
 	}
 ];
 function findClient(id) {
@@ -953,33 +969,84 @@ function resolveLaunchCommand(opts) {
 		args: ["mcp"]
 	};
 }
-/** 单个客户端的配置条目 */
-function buildEntry(spec, launch) {
-	const base = {
-		command: launch.command,
-		args: launch.args
-	};
-	return spec.needsType ? {
-		type: "stdio",
-		...base
-	} : base;
+/** 单个客户端的配置条目；OpenCode 旧布局还需要 enabled: true */
+function buildEntry(spec, launch, layout = "auto") {
+	const entry = {};
+	if (spec.typeValue !== void 0) entry["type"] = spec.typeValue;
+	if (spec.commandForm === "command-array") entry["command"] = [launch.command, ...launch.args];
+	else {
+		entry["command"] = launch.command;
+		entry["args"] = launch.args;
+	}
+	if (spec.extraFields !== void 0) Object.assign(entry, spec.extraFields);
+	if (spec.id === "opencode" && layout === "legacy") entry["enabled"] = true;
+	return entry;
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* 解析 server 表在配置里的路径。
+*
+* OpenCode 有两套布局：V2 把 server 放在 `mcp.servers` 下，旧布局直接放在 `mcp` 下。
+* 已有文件按实际内容判断（避免把条目写到当前版本不读的位置），新文件用官方当前的 V2。
+*/
+function resolveRootPath(spec, existingRoot, layout = "auto") {
+	if (spec.id !== "opencode") return spec.rootPath;
+	if (layout === "legacy") return ["mcp"];
+	if (layout === "v2") return ["mcp", "servers"];
+	const mcp = existingRoot?.["mcp"];
+	if (isRecord$1(mcp)) {
+		if (isRecord$1(mcp["servers"])) return ["mcp", "servers"];
+		if (Object.values(mcp).some((v) => isRecord$1(v) && (typeof v["type"] === "string" || "command" in v))) return ["mcp"];
+	}
+	return ["mcp", "servers"];
 }
 /** Codex 用的 TOML 片段（改 TOML 风险高，只输出不写入） */
 function tomlSnippet(launch, name = "paintress") {
 	const args = launch.args.map((a) => JSON.stringify(a)).join(", ");
 	return `[mcp_servers.${name}]\ncommand = ${JSON.stringify(launch.command)}\nargs = [${args}]\n`;
 }
-/** JSON 客户端用的片段（含顶层键） */
+/** JSON 客户端用的片段（含嵌套路径，OpenCode 按默认布局） */
 function jsonSnippet(spec, launch, name = "paintress") {
-	return JSON.stringify({ [spec.rootKey]: { [name]: buildEntry(spec, launch) } }, null, 2);
+	const path = resolveRootPath(spec, null);
+	const entry = buildEntry(spec, launch, path.length === 1 ? "legacy" : "v2");
+	let cursor = { [name]: entry };
+	for (const key of [...path].reverse()) cursor = { [key]: cursor };
+	return JSON.stringify(cursor, null, 2);
 }
 // src/integrations/install.ts
 /**
 * 配置写入：解析 → 合并 → 备份 → 原子落盘。
 * 只动 `rootKey` 下名为 `paintress` 的那一条，其余内容与顺序保持不变（JSON 重新序列化）。
 */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 按路径取出 server 表（不存在或类型不对时返回空对象） */
+function readTable(root, path) {
+	let cursor = root;
+	for (const key of path) {
+		if (!isRecord(cursor)) return {};
+		cursor = cursor[key];
+	}
+	return isRecord(cursor) ? { ...cursor } : {};
+}
+/** 按路径写回 server 表，沿途缺失的层级补建，其余键原样保留 */
+function writeTable(root, path, table) {
+	let cursor = root;
+	path.forEach((key, index) => {
+		if (index === path.length - 1) {
+			cursor[key] = table;
+			return;
+		}
+		const next = isRecord(cursor[key]) ? { ...cursor[key] } : {};
+		cursor[key] = next;
+		cursor = next;
+	});
+}
 /** 纯函数：把 paintress 条目并入现有配置文本 */
-function planJsonMerge(spec, path, existing, launch) {
+function planJsonMerge(spec, path, existing, launch, options = {}) {
 	const base = {
 		spec,
 		path,
@@ -1024,9 +1091,10 @@ function planJsonMerge(spec, path, existing, launch) {
 			detail: "配置文件不是合法 JSON，未改动"
 		};
 	}
-	const servers = root[spec.rootKey];
-	const table = typeof servers === "object" && servers !== null && !Array.isArray(servers) ? { ...servers } : {};
-	const entry = buildEntry(spec, launch);
+	const rootPath = resolveRootPath(spec, root, options.opencodeLayout ?? "auto");
+	const layout = spec.id === "opencode" && rootPath.length === 1 ? "legacy" : "v2";
+	const table = readTable(root, rootPath);
+	const entry = buildEntry(spec, launch, layout);
 	const current = table["paintress"];
 	if (JSON.stringify(current) === JSON.stringify(entry)) return {
 		...base,
@@ -1036,7 +1104,7 @@ function planJsonMerge(spec, path, existing, launch) {
 	};
 	const existed = current !== void 0;
 	table["paintress"] = entry;
-	root[spec.rootKey] = table;
+	writeTable(root, rootPath, table);
 	return {
 		...base,
 		status: existed ? "update" : existing === null ? "create" : "update",
@@ -1076,7 +1144,8 @@ const FLAG_KEYS = /* @__PURE__ */ new Set([
 	"port",
 	"idle",
 	"daemon",
-	"dry-run"
+	"dry-run",
+	"opencode-layout"
 ]);
 const BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
 	"regex",
@@ -1144,9 +1213,13 @@ async function call(tool, args) {
 }
 /** 入口：返回退出码（可单测） */
 async function main(argv) {
+	if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version") {
+		console.log(`paintress ${VERSION}`);
+		return 0;
+	}
 	const parsed = parseArgv(argv);
 	if (!parsed) {
-		console.error("用法：paintress <mcp|web|ping|status|watch|unwatch|attach|stop|info|query|get|update|insert|delete|move|batch|render|shot|validate|install|doctor|mcp-config> ...");
+		console.error("用法：paintress <mcp|web|ping|status|watch|unwatch|attach|stop|info|query|get|update|insert|delete|move|batch|render|shot|validate|install|doctor|mcp-config> ...（版本：paintress --version）");
 		return 2;
 	}
 	const { cmd, positionals, flags } = parsed;
@@ -1230,13 +1303,15 @@ async function main(argv) {
 			const unknown = ids.filter((id) => findClient(id) === void 0);
 			if (unknown.length > 0) throw new Error(`未知客户端：${unknown.join(", ")}（可选：${CLIENTS.map((c) => c.id).join(" / ")}）`);
 			const dryRun = cmd === "doctor" || flags["dry-run"] === true;
+			const layoutFlag = flagStr(flags, "opencode-layout") ?? "auto";
+			if (layoutFlag !== "auto" && layoutFlag !== "legacy" && layoutFlag !== "v2") throw new Error(`--opencode-layout 只接受 auto / legacy / v2，收到：${layoutFlag}`);
 			const results = [];
 			for (const id of ids) {
 				const spec = findClient(id);
 				if (spec === void 0) continue;
 				const path = spec.configPath(home, process.platform, process.env);
 				const existing = readConfig(path);
-				const plan = planJsonMerge(spec, path, existing, launch);
+				const plan = planJsonMerge(spec, path, existing, launch, { opencodeLayout: layoutFlag });
 				if (cmd === "doctor") {
 					results.push({
 						client: spec.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paintress",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Design-document operation layer for AI agents: read, query, edit, render",
   "type": "module",
   "license": "MIT",
@@ -22,7 +22,7 @@
     }
   },
   "bin": {
-    "paintress": "./dist/cli.js"
+    "paintress": "dist/cli.js"
   },
   "files": [
     "dist",