@openspecui/core 1.0.0 → 1.0.2

package/dist/index.mjs

@@ -1077,6 +1077,15 @@ async function reactiveReadFile(filepath) {
 	return state.get();
 }
 /**
+* 主动更新响应式文件缓存（用于写入后立即推送订阅）
+*
+* 仅当该文件已有缓存状态时生效；不会创建新的监听器。
+*/
+function updateReactiveFileCache(filepath, content) {
+	const key = `file:${resolve(filepath)}`;
+	stateCache$1.get(key)?.set(content);
+}
+/**
 * 响应式读取目录内容
 *
 * 特性：
@@ -1870,20 +1879,124 @@ function createFileChangeObservable(watcher) {
 //#endregion
 //#region src/config.ts
 const execAsync = promisify(exec);
-/** 默认的 fallback CLI 命令（数组形式） */
-const FALLBACK_CLI_COMMAND = ["npx", "@fission-ai/openspec"];
-/** 全局 openspec 命令（数组形式） */
-const GLOBAL_CLI_COMMAND = ["openspec"];
-/** 缓存检测到的 CLI 命令 */
-let detectedCliCommand = null;
+const CLI_PROBE_TIMEOUT_MS = 2e4;
+const THEME_VALUES = [
+	"light",
+	"dark",
+	"system"
+];
+const CURSOR_STYLE_VALUES = [
+	"block",
+	"underline",
+	"bar"
+];
+const BASE_PACKAGE_MANAGER_RUNNERS = [
+	{
+		id: "npx",
+		source: "npx",
+		commandParts: [
+			"npx",
+			"-y",
+			"@fission-ai/openspec"
+		]
+	},
+	{
+		id: "bunx",
+		source: "bunx",
+		commandParts: ["bunx", "@fission-ai/openspec"]
+	},
+	{
+		id: "deno",
+		source: "deno",
+		commandParts: [
+			"deno",
+			"run",
+			"-A",
+			"npm:@fission-ai/openspec"
+		]
+	},
+	{
+		id: "pnpm",
+		source: "pnpm",
+		commandParts: [
+			"pnpm",
+			"dlx",
+			"@fission-ai/openspec"
+		]
+	},
+	{
+		id: "yarn",
+		source: "yarn",
+		commandParts: [
+			"yarn",
+			"dlx",
+			"@fission-ai/openspec"
+		]
+	}
+];
+function tokenizeCliCommand(input) {
+	const tokens = [];
+	let current = "";
+	let quote = null;
+	let tokenStarted = false;
+	for (let index = 0; index < input.length; index += 1) {
+		const char = input[index];
+		if (quote) {
+			if (char === quote) {
+				quote = null;
+				tokenStarted = true;
+				continue;
+			}
+			if (char === "\\") {
+				const next = input[index + 1];
+				if (next && (next === quote || next === "\\")) {
+					current += next;
+					tokenStarted = true;
+					index += 1;
+					continue;
+				}
+			}
+			current += char;
+			tokenStarted = true;
+			continue;
+		}
+		if (char === "\"" || char === "'") {
+			quote = char;
+			tokenStarted = true;
+			continue;
+		}
+		if (char === "\\") {
+			const next = input[index + 1];
+			if (next && /[\s"'\\]/.test(next)) {
+				current += next;
+				tokenStarted = true;
+				index += 1;
+				continue;
+			}
+			current += char;
+			tokenStarted = true;
+			continue;
+		}
+		if (/\s/.test(char)) {
+			if (tokenStarted) {
+				tokens.push(current);
+				current = "";
+				tokenStarted = false;
+			}
+			continue;
+		}
+		current += char;
+		tokenStarted = true;
+	}
+	if (tokenStarted) tokens.push(current);
+	return tokens;
+}
 /**
 * 解析 CLI 命令字符串为数组
 *
 * 支持两种格式：
 * 1. JSON 数组：以 `[` 开头，如 `["npx", "@fission-ai/openspec"]`
-* 2. 简单字符串：用空格分割，如 `npx @fission-ai/openspec`
-*
-* 注意：简单字符串解析不支持带引号的参数，如需复杂命令请使用 JSON 数组格式
+* 2. shell-like 字符串：支持引号与基础转义
 */
 function parseCliCommand(command) {
 	const trimmed = command.trim();
@@ -1894,7 +2007,144 @@ function parseCliCommand(command) {
 	} catch (err) {
 		throw new Error(`Failed to parse CLI command as JSON array: ${err instanceof Error ? err.message : err}`);
 	}
-	return trimmed.split(/\s+/).filter(Boolean);
+	const tokens = tokenizeCliCommand(trimmed);
+	if (tokens.length !== 1) return tokens;
+	const firstChar = trimmed[0];
+	const lastChar = trimmed[trimmed.length - 1];
+	if (firstChar !== "\"" && firstChar !== "'" || firstChar !== lastChar) return tokens;
+	const inner = trimmed.slice(1, -1).trim();
+	if (!inner) return tokens;
+	const innerTokens = tokenizeCliCommand(inner.replace(/\\(["'])/g, "$1"));
+	if (innerTokens.length > 1 && innerTokens.slice(1).some((token) => token.startsWith("-"))) return innerTokens;
+	return tokens;
+}
+function commandToString(commandParts) {
+	const formatToken = (token) => {
+		if (!token) return "\"\"";
+		if (!/[\s"'\\]/.test(token)) return token;
+		return JSON.stringify(token);
+	};
+	return commandParts.map(formatToken).join(" ").trim();
+}
+function getRunnerPriorityFromUserAgent(userAgent) {
+	if (!userAgent) return null;
+	if (userAgent.startsWith("bun")) return "bunx";
+	if (userAgent.startsWith("npm")) return "npx";
+	if (userAgent.startsWith("deno")) return "deno";
+	if (userAgent.startsWith("pnpm")) return "pnpm";
+	if (userAgent.startsWith("yarn")) return "yarn";
+	return null;
+}
+function buildCliRunnerCandidates(options) {
+	const candidates = [];
+	const configuredCommandParts = options.configuredCommandParts?.filter(Boolean) ?? [];
+	if (configuredCommandParts.length > 0) candidates.push({
+		id: "configured",
+		source: "config.cli.command",
+		commandParts: configuredCommandParts
+	});
+	candidates.push({
+		id: "openspec",
+		source: "openspec",
+		commandParts: ["openspec"]
+	});
+	const packageRunners = [...BASE_PACKAGE_MANAGER_RUNNERS];
+	const preferred = getRunnerPriorityFromUserAgent(options.userAgent);
+	if (preferred) {
+		const index = packageRunners.findIndex((item) => item.id === preferred);
+		if (index > 0) {
+			const [runner] = packageRunners.splice(index, 1);
+			packageRunners.unshift(runner);
+		}
+	}
+	return [...candidates, ...packageRunners];
+}
+function createCleanCliEnv(baseEnv = process.env) {
+	const env = { ...baseEnv };
+	for (const key of Object.keys(env)) if (key.startsWith("npm_config_") || key.startsWith("npm_package_") || key === "npm_execpath" || key === "npm_lifecycle_event" || key === "npm_lifecycle_script") delete env[key];
+	return env;
+}
+async function probeCliRunner(candidate, cwd, env) {
+	const [cmd, ...cmdArgs] = candidate.commandParts;
+	return new Promise((resolve$1) => {
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill();
+		}, CLI_PROBE_TIMEOUT_MS);
+		const child = spawn(cmd, [...cmdArgs, "--version"], {
+			cwd,
+			shell: false,
+			env
+		});
+		child.stdout?.on("data", (data) => {
+			stdout += data.toString();
+		});
+		child.stderr?.on("data", (data) => {
+			stderr += data.toString();
+		});
+		child.on("error", (err) => {
+			clearTimeout(timer);
+			const code = err.code;
+			const suffix = code ? ` (${code})` : "";
+			resolve$1({
+				source: candidate.source,
+				command: commandToString(candidate.commandParts),
+				success: false,
+				error: `${err.message}${suffix}`,
+				exitCode: null
+			});
+		});
+		child.on("close", (exitCode) => {
+			clearTimeout(timer);
+			if (timedOut) {
+				resolve$1({
+					source: candidate.source,
+					command: commandToString(candidate.commandParts),
+					success: false,
+					error: "CLI probe timed out",
+					exitCode
+				});
+				return;
+			}
+			if (exitCode === 0) {
+				const version = stdout.trim().split("\n")[0] || void 0;
+				resolve$1({
+					source: candidate.source,
+					command: commandToString(candidate.commandParts),
+					success: true,
+					version,
+					exitCode
+				});
+				return;
+			}
+			resolve$1({
+				source: candidate.source,
+				command: commandToString(candidate.commandParts),
+				success: false,
+				error: stderr.trim() || `Exit code ${exitCode ?? "null"}`,
+				exitCode
+			});
+		});
+	});
+}
+async function resolveCliRunner(candidates, cwd, env) {
+	const attempts = [];
+	for (const candidate of candidates) {
+		const attempt = await probeCliRunner(candidate, cwd, env);
+		attempts.push(attempt);
+		if (attempt.success) return {
+			source: attempt.source,
+			command: attempt.command,
+			commandParts: candidate.commandParts,
+			version: attempt.version,
+			attempts
+		};
+	}
+	const details = attempts.map((attempt) => `- ${attempt.command}: ${attempt.error ?? "failed"}`).join("\n");
+	throw new Error(`No available OpenSpec CLI runner.\n${details}`);
 }
 /**
 * 比较两个语义化版本号
@@ -1921,7 +2171,7 @@ function compareVersions(a, b) {
 */
 async function fetchLatestVersion() {
 	try {
-		const { stdout } = await execAsync("npx @fission-ai/openspec --version", { timeout: 6e4 });
+		const { stdout } = await execAsync("npx -y @fission-ai/openspec --version", { timeout: 6e4 });
 		return stdout.trim();
 	} catch {
 		return;
@@ -1951,7 +2201,6 @@ async function sniffGlobalCli() {
 		};
 	}
 	const version = localResult.stdout.trim();
-	detectedCliCommand = GLOBAL_CLI_COMMAND;
 	return {
 		hasGlobal: true,
 		version,
@@ -1960,53 +2209,44 @@ async function sniffGlobalCli() {
 	};
 }
 /**
-* 检测全局安装的 openspec 命令
-* 优先使用全局命令，fallback 到 npx
-*
-* @returns CLI 命令数组
-*/
-async function detectCliCommand() {
-	if (detectedCliCommand !== null) return detectedCliCommand;
-	try {
-		await execAsync(`${process.platform === "win32" ? "where" : "which"} openspec`);
-		detectedCliCommand = GLOBAL_CLI_COMMAND;
-		return detectedCliCommand;
-	} catch {
-		detectedCliCommand = FALLBACK_CLI_COMMAND;
-		return detectedCliCommand;
-	}
-}
-/**
 * 获取默认 CLI 命令（异步，带检测）
 *
 * @returns CLI 命令数组，如 `['openspec']` 或 `['npx', '@fission-ai/openspec']`
 */
 async function getDefaultCliCommand() {
-	return detectCliCommand();
+	return (await resolveCliRunner(buildCliRunnerCandidates({ userAgent: process.env.npm_config_user_agent }).filter((candidate) => candidate.id !== "configured"), process.cwd(), createCleanCliEnv())).commandParts;
 }
 /**
 * 获取默认 CLI 命令的字符串形式（用于 UI 显示）
 */
 async function getDefaultCliCommandString() {
-	return (await detectCliCommand()).join(" ");
+	return commandToString(await getDefaultCliCommand());
 }
+const TerminalConfigSchema = z.object({
+	fontSize: z.number().min(8).max(32).default(13),
+	fontFamily: z.string().default(""),
+	cursorBlink: z.boolean().default(true),
+	cursorStyle: z.enum(CURSOR_STYLE_VALUES).default("block"),
+	scrollback: z.number().min(0).max(1e5).default(1e3)
+});
 /**
 * OpenSpecUI 配置 Schema
 *
 * 存储在 openspec/.openspecui.json 中，利用文件监听实现响应式更新
 */
 const OpenSpecUIConfigSchema = z.object({
-	cli: z.object({ command: z.string().optional() }).default({}),
-	ui: z.object({ theme: z.enum([
-		"light",
-		"dark",
-		"system"
-	]).default("system") }).default({})
+	cli: z.object({
+		command: z.string().optional(),
+		args: z.array(z.string()).optional()
+	}).default({}),
+	theme: z.enum(THEME_VALUES).default("system"),
+	terminal: TerminalConfigSchema.default(TerminalConfigSchema.parse({}))
 });
 /** 默认配置（静态，用于测试和类型） */
 const DEFAULT_CONFIG = {
 	cli: {},
-	ui: { theme: "system" }
+	theme: "system",
+	terminal: TerminalConfigSchema.parse({})
 };
 /**
 * 配置管理器
@@ -2016,7 +2256,11 @@ const DEFAULT_CONFIG = {
 */
 var ConfigManager = class {
 	configPath;
+	projectDir;
+	resolvedRunner = null;
+	resolvingRunnerPromise = null;
 	constructor(projectDir) {
+		this.projectDir = projectDir;
 		this.configPath = join(projectDir, "openspec", ".openspecui.json");
 	}
 	/**
@@ -2046,43 +2290,140 @@ var ConfigManager = class {
 	*/
 	async writeConfig(config) {
 		const current = await this.readConfig();
+		const nextCli = { ...current.cli };
+		if (config.cli && Object.prototype.hasOwnProperty.call(config.cli, "command")) {
+			const trimmed = config.cli.command?.trim();
+			if (trimmed) nextCli.command = trimmed;
+			else {
+				delete nextCli.command;
+				delete nextCli.args;
+			}
+		}
+		if (config.cli && Object.prototype.hasOwnProperty.call(config.cli, "args")) {
+			const args = (config.cli.args ?? []).map((arg) => arg.trim()).filter(Boolean);
+			if (args.length > 0) nextCli.args = args;
+			else delete nextCli.args;
+		}
+		if (!nextCli.command) delete nextCli.args;
 		const merged = {
 			...current,
-			...config,
-			cli: {
-				...current.cli,
-				...config.cli
-			},
-			ui: {
-				...current.ui,
-				...config.ui
+			cli: nextCli,
+			theme: config.theme ?? current.theme,
+			terminal: {
+				...current.terminal,
+				...config.terminal
 			}
 		};
-		await writeFile(this.configPath, JSON.stringify(merged, null, 2), "utf-8");
+		const serialized = JSON.stringify(merged, null, 2);
+		await writeFile(this.configPath, serialized, "utf-8");
+		updateReactiveFileCache(this.configPath, serialized);
+		this.invalidateResolvedCliRunner();
+	}
+	/**
+	* 解析并缓存可用 CLI runner。
+	*/
+	async resolveCliRunner() {
+		if (this.resolvedRunner) return this.resolvedRunner;
+		if (this.resolvingRunnerPromise) return this.resolvingRunnerPromise;
+		this.resolvingRunnerPromise = this.resolveCliRunnerUncached().then((runner) => {
+			this.resolvedRunner = runner;
+			return runner;
+		}).finally(() => {
+			this.resolvingRunnerPromise = null;
+		});
+		return this.resolvingRunnerPromise;
+	}
+	async resolveCliRunnerUncached() {
+		const config = await this.readConfig();
+		const configuredCommandParts = this.getConfiguredCommandParts(config.cli);
+		const hasConfiguredCommand = configuredCommandParts.length > 0;
+		const resolved = await resolveCliRunner(hasConfiguredCommand ? [{
+			id: "configured",
+			source: "config.cli.command",
+			commandParts: configuredCommandParts
+		}] : buildCliRunnerCandidates({
+			configuredCommandParts,
+			userAgent: process.env.npm_config_user_agent
+		}), this.projectDir, createCleanCliEnv());
+		if (!hasConfiguredCommand) {
+			const [resolvedCommand, ...resolvedArgs] = resolved.commandParts;
+			const currentCommand = config.cli.command?.trim();
+			const currentArgs = config.cli.args ?? [];
+			if (currentCommand !== resolvedCommand || currentArgs.length !== resolvedArgs.length || currentArgs.some((arg, index) => arg !== resolvedArgs[index])) await this.writeConfig({ cli: {
+				command: resolvedCommand,
+				args: resolvedArgs
+			} });
+		}
+		return resolved;
 	}
 	/**
 	* 获取 CLI 命令（数组形式）
-	*
-	* 优先级：配置文件 > 全局 openspec 命令 > npx fallback
-	*
-	* @returns CLI 命令数组，如 `['openspec']` 或 `['npx', '@fission-ai/openspec']`
 	*/
 	async getCliCommand() {
-		const config = await this.readConfig();
-		if (config.cli.command) return parseCliCommand(config.cli.command);
-		return getDefaultCliCommand();
+		return (await this.resolveCliRunner()).commandParts;
 	}
 	/**
 	* 获取 CLI 命令的字符串形式（用于 UI 显示）
 	*/
 	async getCliCommandString() {
-		return (await this.getCliCommand()).join(" ");
+		return (await this.resolveCliRunner()).command;
+	}
+	/**
+	* 获取 CLI 解析结果（用于诊断）
+	*/
+	async getResolvedCliRunner() {
+		return this.resolveCliRunner();
+	}
+	/**
+	* 清理 CLI 解析缓存（用于 ENOENT 自愈）
+	*/
+	invalidateResolvedCliRunner() {
+		this.resolvedRunner = null;
+		this.resolvingRunnerPromise = null;
 	}
 	/**
 	* 设置 CLI 命令
 	*/
 	async setCliCommand(command) {
-		await this.writeConfig({ cli: { command } });
+		const trimmed = command.trim();
+		if (!trimmed) {
+			await this.writeConfig({ cli: {
+				command: null,
+				args: null
+			} });
+			return;
+		}
+		const commandParts = parseCliCommand(trimmed);
+		if (commandParts.length === 0) {
+			await this.writeConfig({ cli: {
+				command: null,
+				args: null
+			} });
+			return;
+		}
+		const [resolvedCommand, ...resolvedArgs] = commandParts;
+		await this.writeConfig({ cli: {
+			command: resolvedCommand,
+			args: resolvedArgs
+		} });
+	}
+	getConfiguredCommandParts(cli) {
+		const command = cli.command?.trim();
+		if (!command) return [];
+		if (Array.isArray(cli.args) && cli.args.length > 0) return [command, ...cli.args];
+		return parseCliCommand(command);
+	}
+	/**
+	* 设置主题
+	*/
+	async setTheme(theme) {
+		await this.writeConfig({ theme });
+	}
+	/**
+	* 设置终端配置（部分更新）
+	*/
+	async setTerminalConfig(terminal) {
+		await this.writeConfig({ terminal });
 	}
 };
 
@@ -2091,50 +2432,24 @@ var ConfigManager = class {
 /**
 * CLI 执行器
 *
-* 负责调用外部 openspec CLI 命令。
-* 命令前缀从 ConfigManager 获取，支持：
-* - ['npx', '@fission-ai/openspec'] (默认)
-* - ['openspec'] (全局安装)
-* - 自定义数组或字符串
-*
-* 注意：所有命令都使用 shell: false 执行，避免 shell 注入风险
+* 负责调用外部 openspec CLI 命令，统一通过 ConfigManager 的 runner 解析结果执行。
+* 所有命令都使用 shell: false，避免 shell 注入风险。
 */
 var CliExecutor = class {
 	constructor(configManager, projectDir) {
 		this.configManager = configManager;
 		this.projectDir = projectDir;
 	}
-	/**
-	* 创建干净的环境变量，移除 pnpm 特有的配置
-	* 避免 pnpm 环境变量污染 npx/npm 执行
-	*/
-	getCleanEnv() {
-		const env = { ...process.env };
-		for (const key of Object.keys(env)) if (key.startsWith("npm_config_") || key.startsWith("npm_package_") || key === "npm_execpath" || key === "npm_lifecycle_event" || key === "npm_lifecycle_script") delete env[key];
-		return env;
-	}
-	/**
-	* 构建完整命令数组
-	*
-	* @param args CLI 参数，如 ['init'] 或 ['archive', 'change-id']
-	* @returns [command, ...commandArgs, ...args]
-	*/
 	async buildCommandArray(args) {
 		return [...await this.configManager.getCliCommand(), ...args];
 	}
-	/**
-	* 执行 CLI 命令
-	*
-	* @param args CLI 参数，如 ['init'] 或 ['archive', 'change-id']
-	* @returns 执行结果
-	*/
-	async execute(args) {
-		const [cmd, ...cmdArgs] = await this.buildCommandArray(args);
+	runCommandOnce(fullCommand) {
+		const [cmd, ...cmdArgs] = fullCommand;
 		return new Promise((resolve$1) => {
 			const child = spawn(cmd, cmdArgs, {
 				cwd: this.projectDir,
 				shell: false,
-				env: this.getCleanEnv()
+				env: createCleanCliEnv()
 			});
 			let stdout = "";
 			let stderr = "";
@@ -2153,19 +2468,50 @@ var CliExecutor = class {
 				});
 			});
 			child.on("error", (err) => {
+				const errorCode = err.code;
+				const errorMessage = err.message + (errorCode ? ` (${errorCode})` : "");
 				resolve$1({
 					success: false,
 					stdout,
-					stderr: stderr + "\n" + err.message,
-					exitCode: null
+					stderr: stderr ? `${stderr}\n${errorMessage}` : errorMessage,
+					exitCode: null,
+					errorCode
 				});
 			});
 		});
 	}
+	async executeInternal(args, allowRetry) {
+		let fullCommand;
+		try {
+			fullCommand = await this.buildCommandArray(args);
+		} catch (err) {
+			return {
+				success: false,
+				stdout: "",
+				stderr: err instanceof Error ? err.message : String(err),
+				exitCode: null
+			};
+		}
+		const result = await this.runCommandOnce(fullCommand);
+		if (allowRetry && result.errorCode === "ENOENT") {
+			this.configManager.invalidateResolvedCliRunner();
+			return this.executeInternal(args, false);
+		}
+		return {
+			success: result.success,
+			stdout: result.stdout,
+			stderr: result.stderr,
+			exitCode: result.exitCode
+		};
+	}
+	/**
+	* 执行 CLI 命令
+	*/
+	async execute(args) {
+		return this.executeInternal(args, true);
+	}
 	/**
 	* 执行 openspec init（非交互式）
-	*
-	* @param tools 工具列表，如 ['claude', 'cursor'] 或 'all' 或 'none'
 	*/
 	async init(tools = "all") {
 		const toolsArg = Array.isArray(tools) ? tools.join(",") : tools;
@@ -2177,9 +2523,6 @@ var CliExecutor = class {
 	}
 	/**
 	* 执行 openspec archive <changeId>（非交互式）
-	*
-	* @param changeId 要归档的 change ID
-	* @param options 选项
 	*/
 	async archive(changeId, options = {}) {
 		const args = [
@@ -2236,75 +2579,108 @@ var CliExecutor = class {
 	}
 	/**
 	* 检查 CLI 是否可用
-	* @param timeout 超时时间（毫秒），默认 10 秒
 	*/
 	async checkAvailability(timeout = 1e4) {
 		try {
-			const result = await Promise.race([this.execute(["--version"]), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("CLI check timed out")), timeout))]);
-			if (result.success) return {
+			const resolved = await Promise.race([this.configManager.getResolvedCliRunner(), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("CLI runner resolve timed out")), timeout))]);
+			const versionResult = await Promise.race([this.runCommandOnce([...resolved.commandParts, "--version"]), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("CLI check timed out")), timeout))]);
+			if (versionResult.success) return {
 				available: true,
-				version: result.stdout.trim()
+				version: versionResult.stdout.trim() || resolved.version,
+				effectiveCommand: resolved.command,
+				tried: resolved.attempts.map((attempt) => attempt.command)
 			};
 			return {
 				available: false,
-				error: result.stderr || "Unknown error"
+				error: versionResult.stderr || "Unknown error",
+				effectiveCommand: resolved.command,
+				tried: resolved.attempts.map((attempt) => attempt.command)
 			};
 		} catch (err) {
 			return {
 				available: false,
-				error: err instanceof Error ? err.message : "Unknown error"
+				error: err instanceof Error ? err.message : String(err)
 			};
 		}
 	}
 	/**
 	* 流式执行 CLI 命令
-	*
-	* @param args CLI 参数
-	* @param onEvent 事件回调
-	* @returns 取消函数
 	*/
 	async executeStream(args, onEvent) {
-		const fullCommand = await this.buildCommandArray(args);
-		const [cmd, ...cmdArgs] = fullCommand;
-		onEvent({
-			type: "command",
-			data: fullCommand.join(" ")
-		});
-		const child = spawn(cmd, cmdArgs, {
-			cwd: this.projectDir,
-			shell: false,
-			env: this.getCleanEnv()
-		});
-		child.stdout?.on("data", (data) => {
+		let cancelled = false;
+		let activeChild = null;
+		const start = async (allowRetry) => {
+			if (cancelled) return;
+			let fullCommand;
+			try {
+				fullCommand = await this.buildCommandArray(args);
+			} catch (err) {
+				onEvent({
+					type: "stderr",
+					data: err instanceof Error ? err.message : String(err)
+				});
+				onEvent({
+					type: "exit",
+					exitCode: null
+				});
+				return;
+			}
 			onEvent({
-				type: "stdout",
-				data: data.toString()
+				type: "command",
+				data: fullCommand.join(" ")
 			});
-		});
-		child.stderr?.on("data", (data) => {
-			onEvent({
-				type: "stderr",
-				data: data.toString()
+			const [cmd, ...cmdArgs] = fullCommand;
+			const child = spawn(cmd, cmdArgs, {
+				cwd: this.projectDir,
+				shell: false,
+				env: createCleanCliEnv()
 			});
-		});
-		child.on("close", (exitCode) => {
-			onEvent({
-				type: "exit",
-				exitCode
+			activeChild = child;
+			child.stdout?.on("data", (data) => {
+				onEvent({
+					type: "stdout",
+					data: data.toString()
+				});
 			});
-		});
-		child.on("error", (err) => {
-			onEvent({
-				type: "stderr",
-				data: err.message
+			child.stderr?.on("data", (data) => {
+				onEvent({
+					type: "stderr",
+					data: data.toString()
+				});
 			});
-			onEvent({
-				type: "exit",
-				exitCode: null
+			child.on("close", (exitCode) => {
+				if (activeChild !== child) return;
+				activeChild = null;
+				onEvent({
+					type: "exit",
+					exitCode
+				});
 			});
-		});
+			child.on("error", (err) => {
+				if (activeChild !== child) return;
+				activeChild = null;
+				const code = err.code;
+				const message = err.message + (code ? ` (${code})` : "");
+				if (allowRetry && code === "ENOENT" && !cancelled) {
+					this.configManager.invalidateResolvedCliRunner();
+					start(false);
+					return;
+				}
+				onEvent({
+					type: "stderr",
+					data: message
+				});
+				onEvent({
+					type: "exit",
+					exitCode: null
+				});
+			});
+		};
+		await start(true);
 		return () => {
-			child.kill();
+			cancelled = true;
+			activeChild?.kill();
+			activeChild = null;
 		};
 	}
 	/**
@@ -2333,13 +2709,6 @@ var CliExecutor = class {
 	}
 	/**
 	* 流式执行任意命令（数组形式）
-	*
-	* 用于执行不需要 openspec CLI 前缀的命令，如 npm install。
-	* 使用 shell: false 避免 shell 注入风险。
-	*
-	* @param command 命令数组，如 ['npm', 'install', '-g', '@fission-ai/openspec']
-	* @param onEvent 事件回调
-	* @returns 取消函数
 	*/
 	executeCommandStream(command, onEvent) {
 		const [cmd, ...cmdArgs] = command;
@@ -2350,7 +2719,7 @@ var CliExecutor = class {
 		const child = spawn(cmd, cmdArgs, {
 			cwd: this.projectDir,
 			shell: false,
-			env: this.getCleanEnv()
+			env: createCleanCliEnv()
 		});
 		child.stdout?.on("data", (data) => {
 			onEvent({
@@ -2371,9 +2740,10 @@ var CliExecutor = class {
 			});
 		});
 		child.on("error", (err) => {
+			const code = err.code;
 			onEvent({
 				type: "stderr",
-				data: err.message
+				data: err.message + (code ? ` (${code})` : "")
 			});
 			onEvent({
 				type: "exit",
@@ -3478,4 +3848,4 @@ const PtyServerMessageSchema = z.discriminatedUnion("type", [
 ]);
 
 //#endregion
-export { AI_TOOLS, ApplyInstructionsSchema, ApplyTaskSchema, ArtifactInstructionsSchema, ArtifactStatusSchema, ChangeFileSchema, ChangeSchema, ChangeStatusSchema, CliExecutor, ConfigManager, DEFAULT_CONFIG, DeltaOperationType, DeltaSchema, DeltaSpecSchema, DependencyInfoSchema, MarkdownParser, OpenSpecAdapter, OpenSpecUIConfigSchema, OpenSpecWatcher, OpsxKernel, ProjectWatcher, PtyAttachMessageSchema, PtyBufferResponseSchema, PtyClientMessageSchema, PtyCloseMessageSchema, PtyCreateMessageSchema, PtyCreatedResponseSchema, PtyErrorCodeSchema, PtyErrorResponseSchema, PtyExitResponseSchema, PtyInputMessageSchema, PtyListMessageSchema, PtyListResponseSchema, PtyOutputResponseSchema, PtyPlatformSchema, PtyResizeMessageSchema, PtyServerMessageSchema, PtyTitleResponseSchema, ReactiveContext, ReactiveState, RequirementSchema, SchemaArtifactSchema, SchemaDetailSchema, SchemaInfoSchema, SchemaResolutionSchema, SpecSchema, TaskSchema, TemplatesSchema, Validator, acquireWatcher, clearCache, closeAllProjectWatchers, closeAllWatchers, contextStorage, createFileChangeObservable, getActiveWatcherCount, getAllToolIds, getAllTools, getAvailableToolIds, getAvailableTools, getCacheSize, getConfiguredTools, getDefaultCliCommand, getDefaultCliCommandString, getProjectWatcher, getToolById, getWatchedProjectDir, initWatcherPool, isGlobPattern, isToolConfigured, isWatcherPoolInitialized, parseCliCommand, reactiveExists, reactiveReadDir, reactiveReadFile, reactiveStat, sniffGlobalCli };
+export { AI_TOOLS, ApplyInstructionsSchema, ApplyTaskSchema, ArtifactInstructionsSchema, ArtifactStatusSchema, ChangeFileSchema, ChangeSchema, ChangeStatusSchema, CliExecutor, ConfigManager, DEFAULT_CONFIG, DeltaOperationType, DeltaSchema, DeltaSpecSchema, DependencyInfoSchema, MarkdownParser, OpenSpecAdapter, OpenSpecUIConfigSchema, OpenSpecWatcher, OpsxKernel, ProjectWatcher, PtyAttachMessageSchema, PtyBufferResponseSchema, PtyClientMessageSchema, PtyCloseMessageSchema, PtyCreateMessageSchema, PtyCreatedResponseSchema, PtyErrorCodeSchema, PtyErrorResponseSchema, PtyExitResponseSchema, PtyInputMessageSchema, PtyListMessageSchema, PtyListResponseSchema, PtyOutputResponseSchema, PtyPlatformSchema, PtyResizeMessageSchema, PtyServerMessageSchema, PtyTitleResponseSchema, ReactiveContext, ReactiveState, RequirementSchema, SchemaArtifactSchema, SchemaDetailSchema, SchemaInfoSchema, SchemaResolutionSchema, SpecSchema, TaskSchema, TemplatesSchema, TerminalConfigSchema, Validator, acquireWatcher, buildCliRunnerCandidates, clearCache, closeAllProjectWatchers, closeAllWatchers, contextStorage, createCleanCliEnv, createFileChangeObservable, getActiveWatcherCount, getAllToolIds, getAllTools, getAvailableToolIds, getAvailableTools, getCacheSize, getConfiguredTools, getDefaultCliCommand, getDefaultCliCommandString, getProjectWatcher, getToolById, getWatchedProjectDir, initWatcherPool, isGlobPattern, isToolConfigured, isWatcherPoolInitialized, parseCliCommand, reactiveExists, reactiveReadDir, reactiveReadFile, reactiveStat, sniffGlobalCli };