@deepseek-ai/dsh-native-command 0.1.7-rc.1 → 0.2.0-rc.1

package/README.i18n.yaml

@@ -1,6 +1,52 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/native-command/README.md
-README.md: c9e1f3fd936093bcad334390704b97630f7acfc8
-README.zh.md: 2c6feadbb8e09391ab5f112e0129b669f6c33127
+/:
+  en: 3e0acbcc586810bb
+  zh: 688d34f126d1450e
+/deepseek-ai-dsh-native-command:
+  en: 5ebca99c0488e1c8
+  zh: 24b2f8f341ff648d
+/deepseek-ai-dsh-native-command/summary:
+  en: 8369dd3eb2af0781
+  zh: fa9dfd927cc8aaad
+/deepseek-ai-dsh-native-command/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-native-command/use-this-package:
+  en: aba695cba233905f
+  zh: c6359da30eb8e372
+/deepseek-ai-dsh-native-command/use-this-package/running-a-command:
+  en: 6dbc6c9bf6db34be
+  zh: 9ab16a86ca5abcc2
+/deepseek-ai-dsh-native-command/use-this-package/injecting-the-command-boundary:
+  en: 987bed629737b59d
+  zh: 258e30f813b0edcb
+/deepseek-ai-dsh-native-command/use-this-package/opening-a-host-path:
+  en: b4ec677605b12ff8
+  zh: f35256957eea141a
+/deepseek-ai-dsh-native-command/understand-the-implementation:
+  en: 78e86818bea36f9f
+  zh: 71dc1ad3e4cbe9f1
+/deepseek-ai-dsh-native-command/understand-the-implementation/source-map:
+  en: a19bb4cb9f6de785
+  zh: cc930d8facf1ca07
+/deepseek-ai-dsh-native-command/understand-the-implementation/what-execfile-gives-the-runner:
+  en: ce6180ce8209db94
+  zh: 30000a1a073110e8
+/deepseek-ai-dsh-native-command/further-exploration:
+  en: a3af562edb6e0385
+  zh: e26e2c311c07d1c5
+/deepseek-ai-dsh-native-command/model-experience:
+  en: d478457568b9517e
+  zh: 0460368e7567a13f
+/deepseek-ai-dsh-native-command/model-experience/kv-cache-effect:
+  en: 296c060e95197cc5
+  zh: b9d3fdf11b5ebe1e
+/deepseek-ai-dsh-native-command/known-limitations-and-deferred-work:
+  en: d3af15e86d679b8e
+  zh: ee5aa3c8cbd9d2db
+/deepseek-ai-dsh-native-command/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-native-command` runs host executables without a shell and opens Host filesystem paths through the desktop. The command runner captures utf8 output, propagates cancellation, and hides transient Windows consoles. The path opener supports default-application and text-editor intents, browser-renderable documents, WSL translation, and desktop availability checks. It is a library, not a plugin: no `ctx`, no state, no events.
+`dsh-native-command` runs host executables without a shell and opens Host filesystem paths through the desktop. The command runner captures utf8 output, propagates cancellation, and requires explicit Windows startup visibility. The path opener supports default-application and text-editor intents, browser-renderable documents, WSL translation, and desktop availability checks. It is a library, not a plugin: no `ctx`, no state, no events.
 
 ## Table of Contents
 
@@ -34,10 +34,10 @@ import { runNativeCommand } from '@deepseek-ai/dsh-native-command'
 
 declare const script: string
 declare const signal: AbortSignal
-const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], signal)
+const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], signal, 'hidden')
 ```
 
-On exit 0 the call resolves with captured stdout and stderr. On any failure it rejects with the exit `code` and both captured streams attached, so a caller can tell a missing tool (`ENOENT`), a cancellation (`ABORT_ERR`), and a real command failure apart without re-running the command.
+On exit 0 the call resolves with captured stdout and stderr. On any failure it rejects with the exit `code` and both captured streams attached, so a caller can tell a missing tool (`ENOENT`), a cancellation (`ABORT_ERR`), and a real command failure apart without re-running the command. The required fourth argument, `window: 'hidden' | 'visible'`, controls Windows startup visibility and has no effect on other platforms. Background commands pass `'hidden'`; GUI launchers pass `'visible'`. The path opener selects `'visible'` for Explorer, including WSL handoffs and file selection, because hiding Explorer also hides its folder window.
 
 ### Injecting the command boundary
 
@@ -49,7 +49,7 @@ The `NativeCommandRunner` type is the injectable command boundary for host integ
 
 `revealNativePath(path, signal)` selects the file in Finder or Explorer, including WSL path translation, and opens its parent directory through `xdg-open` on desktop Linux. `nativeFileManager()` identifies that action for Host-derived UI labels; desktop availability remains a separate `canOpenNativePath()` check. Callers must authorize the absolute file path before invoking either operation. Platform dispatch is covered by injected-runner tests; native desktop verification belongs to the corresponding platform. Explorer receives an encoded file URI as a separate argument. Its exit code 1 is accepted as a delegated handoff; cancellation, missing executables, and other exit codes still reject. This acknowledgement does not prove that an application opened the file or that a window selected it.
 
-`nativeFileApplications(path, signal)` returns registered applications, localized names, icons, and the current default. macOS 12 and later use LaunchServices; Windows uses Shell association handlers; Linux uses GIO with shared XDG desktop-entry and icon lookup. On macOS, copies sharing a bundle identifier and display name (staged self-updates, per-version installs) collapse to the system default, else the highest version; deliberate side-by-side installs keep distinct display names and both entries. `openNativeFileApplication(path, application, signal)` revalidates the handler against the complete registered list, so copies collapsed out of the display list stay openable, and never changes the system default. Windows delegates invocation to the Shell, and Linux delegates argument expansion to `gio launch`. WSL translates the path and uses the Windows adapter. Callers authorize the local file path. Native integration tests use private Windows file associations and Linux XDG roots on their respective platforms.
+`nativeFileApplications(path, signal)` returns registered applications, localized names, icons, and the current default. macOS 12 and later use LaunchServices; Windows uses Shell association handlers and resolves a packaged application’s indirect icon reference before extraction; Linux uses GIO with shared XDG desktop-entry and icon lookup. On macOS, copies sharing a bundle identifier and display name (staged self-updates, per-version installs) collapse to the system default, else the highest version; deliberate side-by-side installs keep distinct display names and both entries. `openNativeFileApplication(path, application, signal)` revalidates the handler against the complete registered list, so copies collapsed out of the display list stay openable, and never changes the system default. Windows delegates invocation to the Shell, and Linux delegates argument expansion to `gio launch`. WSL translates the path and uses the Windows adapter. Callers authorize the local file path. Native integration tests use private Windows file associations and Linux XDG roots on their respective platforms.
 
 -----
 
@@ -72,7 +72,7 @@ The command runner is a thin wrapper over Node's `execFile`. The path opener sel
 
 ### What execFile gives the runner
 
-`execFile` spawns the executable directly with an argv array — no shell string, no shell interpretation of the arguments. The `signal` option terminates the child when the caller's abort fires; `windowsHide` suppresses the transient console window on Windows. On a non-zero exit or spawn error, the callback attaches `code`, `stdout`, and `stderr` to the rejected error and keeps the original error as `cause`.
+`execFile` spawns the executable directly with an argv array — no shell string, no shell interpretation of the arguments. The `signal` option terminates the child when the caller's abort fires; the runner maps `window` to Node's `windowsHide` option. On a non-zero exit or spawn error, the callback attaches `code`, `stdout`, and `stderr` to the rejected error and keeps the original error as `cause`.
 
 </details>
 
@@ -109,6 +109,7 @@ Linux association discovery and explicit launching require GIO. Missing native c
 These limits define when this runner is not the right tool. They are current package constraints, not a task backlog.
 
 - Command output uses Node’s `execFile` buffer limit; oversized replies reject. Use the subprocess capability for streaming output.
+- A Windows handler icon appears only when the Shell resolves its indirect reference; an unresolved reference falls back to the handler executable, and a handler that names none — a packaged handler may report an AUMID or family name — yields no icon.
 - A Windows host needs an interactive desktop session. In a non-interactive session — a service, or a scheduled task without an interactive logon — `explorer.exe` invokes no file association and still exits 1 after about a second (an SSH session 0 on Windows 11 ARM64 build 26200), so an open reports success having opened nothing; a caller's abort signal turns that wait into a timeout rather than a hang. An `Invoke-Item` command resolves the association in-process there, and its directory failure arrives as a non-zero exit code. No fallback for that session is implemented.
 
 <a id="dev-note"></a>

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-`dsh-native-command` 无需 shell 即可运行 Host 可执行文件，并通过桌面打开 Host 文件系统路径。命令运行器捕获 utf8 输出、传播取消，并隐藏 Windows 瞬时控制台。路径打开器支持默认应用与文本编辑器意图、浏览器可渲染文档、WSL 转换与桌面可用性检查。它是库而非插件：没有 `ctx`、无状态、不发事件。
+`dsh-native-command` 无需 shell 即可运行 Host 可执行文件，并通过桌面打开 Host 文件系统路径。命令运行器捕获 utf8 输出、传播取消，并要求显式指定 Windows 启动时的窗口可见性。路径打开器支持默认应用与文本编辑器意图、浏览器可渲染文档、WSL 转换与桌面可用性检查。它是库而非插件：没有 `ctx`、无状态、不发事件。
 
 ## 目录
 
@@ -34,10 +34,10 @@ import { runNativeCommand } from '@deepseek-ai/dsh-native-command'
 
 declare const script: string
 declare const signal: AbortSignal
-const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], signal)
+const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], signal, 'hidden')
 ```
 
-退出码为 0 时，调用解析为捕获到的 stdout 与 stderr。任何失败都会以错误拒绝，错误附带退出 `code` 与两路已捕获输出，因此调用方无需重跑命令即可区分工具缺失（`ENOENT`）、取消（`ABORT_ERR`）与真实的命令失败。
+退出码为 0 时，调用解析为捕获到的 stdout 与 stderr。任何失败都会以错误拒绝，错误附带退出 `code` 与两路已捕获输出，因此调用方无需重跑命令即可区分工具缺失（`ENOENT`）、取消（`ABORT_ERR`）与真实的命令失败。必填的第四个参数 `window: 'hidden' | 'visible'` 控制 Windows 启动时的窗口可见性，在其他平台不生效。后台命令传入 `'hidden'`，GUI 启动程序传入 `'visible'`。路径打开器为 Explorer 选择 `'visible'`，包括 WSL 转交和文件选中操作，因为隐藏 Explorer 也会隐藏它的文件夹窗口。
 
 ### 注入命令边界
 
@@ -49,7 +49,7 @@ const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], s
 
 `revealNativePath(path, signal)` 在 Finder 或文件资源管理器中选中文件，包含 WSL 路径转换；在桌面 Linux 上通过 `xdg-open` 打开上层目录。`nativeFileManager()` 标识该操作，供 UI 根据 Host 选择文案；桌面是否可用仍由独立的 `canOpenNativePath()` 检查决定。调用方必须先授权绝对文件路径，再执行操作。平台分派由注入运行器的测试覆盖；原生桌面验证由对应平台负责。 Explorer 接收独立参数中的编码文件 URI。退出码 1 按已转交请求处理；取消、找不到可执行文件和其他退出码仍然报错。该确认不能证明应用已打开文件，也不能证明桌面窗口已选中文件。
 
-`nativeFileApplications(path, signal)` 返回关联应用、本地化名称、图标和当前默认项。macOS 12 及以上版本使用 LaunchServices，Windows 使用 Shell 关联处理器，Linux 使用 GIO，并共用 XDG 桌面文件和图标读取逻辑。macOS 上 bundle 标识符与显示名都相同的多份拷贝（自更新暂存副本、按版本安装的拷贝）合并为系统默认项，否则保留最高版本；显示名不同的并存安装两项都保留。`openNativeFileApplication(path, application, signal)` 按完整的当前注册列表重新验证关联应用，展示列表中被合并掉的拷贝仍可打开，且不修改系统默认值。Windows 交给 Shell 启动应用，Linux 交给 `gio launch` 展开参数。WSL 转换路径后使用 Windows 适配器。调用方负责验证本地文件路径。原生集成测试分别在相应平台使用独立的 Windows 文件关联和 Linux XDG 目录。
+`nativeFileApplications(path, signal)` 返回关联应用、本地化名称、图标和当前默认项。macOS 12 及以上版本使用 LaunchServices，Windows 使用 Shell 关联处理器并在提取前解析打包应用的间接图标引用，Linux 使用 GIO，并共用 XDG 桌面文件和图标读取逻辑。macOS 上 bundle 标识符与显示名都相同的多份拷贝（自更新暂存副本、按版本安装的拷贝）合并为系统默认项，否则保留最高版本；显示名不同的并存安装两项都保留。`openNativeFileApplication(path, application, signal)` 按完整的当前注册列表重新验证关联应用，展示列表中被合并掉的拷贝仍可打开，且不修改系统默认值。Windows 交给 Shell 启动应用，Linux 交给 `gio launch` 展开参数。WSL 转换路径后使用 Windows 适配器。调用方负责验证本地文件路径。原生集成测试分别在相应平台使用独立的 Windows 文件关联和 Linux XDG 目录。
 
 -----
 
@@ -72,7 +72,7 @@ const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], s
 
 ### execFile 给了运行器什么
 
-`execFile` 以 argv 数组直接 spawn 可执行文件——没有 shell 字符串，参数不经 shell 解释。`signal` 选项在调用方中止触发时终止子进程；`windowsHide` 在 Windows 上抑制瞬时控制台窗口。遇到非零退出或 spawn 错误时，回调把 `code`、`stdout`、`stderr` 挂到被拒绝的错误上，并保留原始错误作为 `cause`。
+`execFile` 以 argv 数组直接 spawn 可执行文件——没有 shell 字符串，参数不经 shell 解释。`signal` 选项在调用方中止触发时终止子进程；`window` 由运行器映射为 Node 的 `windowsHide` 选项。遇到非零退出或 spawn 错误时，回调把 `code`、`stdout`、`stderr` 挂到被拒绝的错误上，并保留原始错误作为 `cause`。
 
 </details>
 
@@ -109,6 +109,7 @@ Linux 的关联查询和指定应用启动需要 GIO。缺少原生命令时查
 这些限制说明本运行器何时不是合适的工具。它们是当前包约束，不是任务积压。
 
 - 命令输出受 Node 的 `execFile` 缓冲上限约束，超过上限时拒绝结果。流式输出由 subprocess 能力处理。
+- Windows 关联处理器的图标只在 Shell 能解析其间接引用时显示；解析失败时回退到处理器的可执行文件，处理器没有给出可执行文件（打包处理器可能只报 AUMID 或家族名）时则没有图标。
 - Windows 主机需要交互桌面会话。在非交互会话（服务，或没有交互登录的计划任务）中，`explorer.exe` 不调用任何文件关联，且仍在约 1 秒后以退出码 1 返回（Windows 11 ARM64 build 26200 的 SSH session 0 实测），于是「打开」会报告成功却什么都没打开；调用方的 abort 信号把这段等待变成超时而不是挂死。同一目标改用 `Invoke-Item` 命令时可在该会话内解析关联，目录失败也会以非零退出码报出。该会话下的兜底尚未实现。
 
 <a id="dev-note"></a>

package/lib/index.js

@@ -1,25 +1,27 @@
 import { execFile } from "node:child_process";
-import { homedir, release } from "node:os";
+import { homedir, release, tmpdir } from "node:os";
 import { dirname, extname, isAbsolute, join, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
-import { readFile, readdir, stat } from "node:fs/promises";
+import { mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 //#region lib/types/runner.js
 /**
 * Shared no-shell `execFile` runner for host-native OS integrations.
 * @module @deepseek-ai/dsh-native-command/runner
 */
 /**
-* Run a host command with utf8 stdio, abort propagation, and Windows hide.
+* Run a host command with utf8 stdio, abort propagation, and explicit GUI visibility.
 * @param command - executable path or PATH name.
 * @param args - argv (never a shell string).
 * @param signal - caller/connection lifetime; abort terminates the child.
+* @param window - Windows startup visibility: `hidden` for background commands,
+* `visible` for GUI launchers. Ignored on other platforms.
 * @returns captured stdout/stderr on exit 0.
 */
-const runNativeCommand = (command, args, signal) => new Promise((resolve, reject) => {
+const runNativeCommand = (command, args, signal, window) => new Promise((resolve, reject) => {
 	execFile(command, [...args], {
 		encoding: "utf8",
 		signal,
-		windowsHide: true
+		windowsHide: window === "hidden"
 	}, (error, stdout, stderr) => {
 		if (error !== null) {
 			reject(Object.assign(new Error(error.message, { cause: error }), {
@@ -77,7 +79,7 @@ async function openInBrowser(path, signal, platform, run, env) {
 	if (platform === "darwin") {
 		let bundle;
 		try {
-			const { stdout } = await run("defaults", ["read", "com.apple.LaunchServices/com.apple.launchservices.secure"], signal);
+			const { stdout } = await run("defaults", ["read", "com.apple.LaunchServices/com.apple.launchservices.secure"], signal, "hidden");
 			bundle = macBundleForHttps(stdout);
 		} catch {
 			return false;
@@ -87,13 +89,13 @@ async function openInBrowser(path, signal, platform, run, env) {
 			"-b",
 			bundle,
 			path
-		], signal);
+		], signal, "hidden");
 		return true;
 	}
 	if (platform === "linux") {
 		const browser = env.BROWSER;
 		if (browser === void 0 || browser === "") return false;
-		await run(browser, [path], signal);
+		await run(browser, [path], signal, "hidden");
 		return true;
 	}
 	return false;
@@ -140,7 +142,7 @@ function explorerTarget(windowsPath) {
 */
 async function runExplorer(args, signal, run) {
 	try {
-		await run("explorer.exe", args, signal);
+		await run("explorer.exe", args, signal, "visible");
 	} catch (error) {
 		signal.throwIfAborted();
 		if (!(error instanceof Error) || !("code" in error) || error.code !== 1) throw error;
@@ -158,7 +160,7 @@ async function openWindowsPath(path, signal, run) {
 }
 /** Translate a WSL path before handing it to the Windows desktop. */
 async function openWslPath(path, signal, run) {
-	const translated = await run("wslpath", ["-w", path], signal);
+	const translated = await run("wslpath", ["-w", path], signal, "hidden");
 	signal.throwIfAborted();
 	const windowsPath = translated.stdout.replace(/[\r\n]+$/, "");
 	if (windowsPath === "") throw new Error("wslpath returned no Windows path");
@@ -172,7 +174,7 @@ async function openNativePathWithIntent(path, signal, intent, internals = {}) {
 	const wsl = platform === "linux" && isWsl(internals);
 	if (!wsl && intent === "default" && BROWSER_DOCUMENTS.has(extname(path).toLowerCase()) && await openInBrowser(path, signal, platform, run, env)) return;
 	if (platform === "darwin") {
-		await run("open", intent === "text-editor" ? ["-t", path] : [path], signal);
+		await run("open", intent === "text-editor" ? ["-t", path] : [path], signal, "hidden");
 		return;
 	}
 	if (platform === "win32") {
@@ -184,7 +186,7 @@ async function openNativePathWithIntent(path, signal, intent, internals = {}) {
 			await openWslPath(path, signal, run);
 			return;
 		}
-		await run("xdg-open", [path], signal);
+		await run("xdg-open", [path], signal, "hidden");
 		return;
 	}
 	throw new Error(`native path opener is unsupported on ${platform}`);
@@ -264,13 +266,13 @@ async function revealNativePath(path, signal, internals = {}) {
 		platform
 	});
 	if (manager === "finder") {
-		await run("open", ["-R", path], signal);
+		await run("open", ["-R", path], signal, "hidden");
 		return;
 	}
 	if (manager === "explorer") {
 		let windowsPath = path;
 		if (platform === "linux") {
-			const translated = await run("wslpath", ["-w", path], signal);
+			const translated = await run("wslpath", ["-w", path], signal, "hidden");
 			signal.throwIfAborted();
 			windowsPath = translated.stdout.replace(/[\r\n]+$/, "");
 			if (windowsPath === "") throw new Error("wslpath returned no Windows path");
@@ -279,7 +281,7 @@ async function revealNativePath(path, signal, internals = {}) {
 		return;
 	}
 	if (manager === "directory") {
-		await run("xdg-open", [dirname(path)], signal);
+		await run("xdg-open", [dirname(path)], signal, "hidden");
 		return;
 	}
 	throw new Error(`native file manager is unsupported on ${platform}`);
@@ -394,7 +396,7 @@ async function linuxFileApplications(path, signal, run, env) {
 		"-a",
 		"standard::content-type",
 		path
-	], signal);
+	], signal, "hidden");
 	const mime = /standard::content-type:\s*(\S+)/.exec(info.stdout)?.[1];
 	if (mime === void 0) throw new Error("GIO did not identify the file content type");
 	const result = await run("env", [
@@ -402,7 +404,7 @@ async function linuxFileApplications(path, signal, run, env) {
 		"gio",
 		"mime",
 		mime
-	], signal);
+	], signal, "hidden");
 	const preferred = /^Default application.*:\s*(.+\.desktop)\s*$/m.exec(result.stdout)?.[1];
 	const ids = [...new Set([...preferred === void 0 ? [] : [preferred], ...result.stdout.split(/\r?\n/).filter((line) => /^\s+.*\.desktop\s*$/.test(line)).map((line) => line.trim())])];
 	const directories = desktopDataDirectories(env.HOME ?? homedir(), env);
@@ -431,6 +433,7 @@ async function linuxFileApplications(path, signal, run, env) {
 }
 //#endregion
 //#region lib/types/file-applications-windows.js
+/** Windows Shell association queries and invocation; paths are encoded data, never PowerShell expressions. */
 /** Shell interfaces are declared in their native vtable order; Invoke preserves packaged-app and DDE handling. */
 const WINDOWS_ASSOCIATIONS = String.raw`
 using System;
@@ -471,6 +474,8 @@ public static class DshFileAssociations {
   static extern int SHDefExtractIcon(string path, int index, uint flags, out IntPtr large, out IntPtr small, uint size);
   [DllImport("user32.dll")]
   static extern bool DestroyIcon(IntPtr icon);
+  [DllImport("shlwapi.dll", CharSet = CharSet.Unicode)]
+  static extern int SHLoadIndirectString(string source, StringBuilder output, uint size, IntPtr reserved);
 
   [DllImport("shlwapi.dll", PreserveSig = false)]
   static extern void SHCreateThreadRef(IntPtr count, out IntPtr reference);
@@ -548,12 +553,18 @@ public static class DshFileAssociations {
     var text = new StringBuilder((int)size);
     return AssocQueryString(0, kind, extension, null, text, ref size) == 0 ? text.ToString() : null;
   }
-  static string IconData(IHandler handler) {
+  // Resolve a packaged application's indirect icon reference, for example
+  // @{Microsoft.WindowsNotepad_...?ms-resource://.../NotepadAppList.png}, to
+  // the resource file the Shell would draw; an unresolved reference is null.
+  static string ResolveIndirectIcon(string source) {
+    var output = new StringBuilder(1024);
+    return SHLoadIndirectString(source, output, (uint)output.Capacity, IntPtr.Zero) == 0 ? output.ToString() : null;
+  }
+  // Read one icon source into a 32px PNG: an image file directly, otherwise the
+  // resource the Shell extracts at the given index. A missing resource is null.
+  static string PngFromIconSource(string source, int index) {
     IntPtr large = IntPtr.Zero, small = IntPtr.Zero;
     try {
-      string source; int index;
-      handler.GetIconLocation(out source, out index);
-      source = Environment.ExpandEnvironmentVariables(source);
       if (Path.GetExtension(source).Equals(".png", StringComparison.OrdinalIgnoreCase)) {
         using (var original = Image.FromFile(source))
         using (var resized = new Bitmap(original, new Size(32, 32)))
@@ -577,6 +588,26 @@ public static class DshFileAssociations {
       if (small != IntPtr.Zero) DestroyIcon(small);
     }
   }
+  // Best-effort fallback: some handlers return their executable path from GetName, but a
+  // packaged handler's name may be an AUMID or family name, which extracts no icon.
+  static string IconData(IHandler handler, string id) {
+    string source = null; int index = 0;
+    try { handler.GetIconLocation(out source, out index); } catch (Exception) {
+      // A handler without a drawable icon location falls back to its name.
+    }
+    if (!String.IsNullOrEmpty(source)) {
+      source = Environment.ExpandEnvironmentVariables(source);
+      if (source.StartsWith("@{", StringComparison.Ordinal) && source.EndsWith("}", StringComparison.Ordinal)) {
+        var resolved = ResolveIndirectIcon(source);
+        if (!String.IsNullOrEmpty(resolved)) source = resolved;
+      }
+      var icon = PngFromIconSource(source, index);
+      if (icon != null) return icon;
+    }
+    return String.IsNullOrEmpty(id) || String.Equals(id, source, StringComparison.OrdinalIgnoreCase)
+      ? null
+      : PngFromIconSource(id, 0);
+  }
   static void Visit(string path, Action<IHandler> visit) {
     var extension = Path.GetExtension(path);
     if (extension.Length == 0) return;
@@ -602,7 +633,7 @@ public static class DshFileAssociations {
       string id, name;
       handler.GetName(out id); handler.GetUIName(out name);
       if (!seen.Add(id)) return;
-      apps.Add(new Application { id = id, name = name, icon = IconData(handler),
+      apps.Add(new Application { id = id, name = name, icon = IconData(handler, id),
         @default = String.Equals(id, executable, StringComparison.OrdinalIgnoreCase) || String.Equals(id, appId, StringComparison.OrdinalIgnoreCase) });
     });
     return apps.ToArray();
@@ -634,7 +665,8 @@ public static class DshFileAssociations {
   }
 }`;
 /**
-* Execute the Windows Shell adapter in a Unicode STA PowerShell process.
+* Execute the Windows Shell adapter in a Unicode STA PowerShell process; the adapter
+* source is a private temporary script file, removed once the call settles.
 * @param path - Windows file path, translated by the caller for WSL.
 * @param application - registered handler to invoke; null requests the application list.
 * @param signal - caller cancellation.
@@ -651,13 +683,25 @@ $path = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${Buffer.fr
 $application = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${Buffer.from(application ?? "").toString("base64")}'))
 ${application === null ? "ConvertTo-Json -InputObject @([DshFileAssociations]::List($path)) -Depth 4 -Compress" : "[DshFileAssociations]::Open($path, $application)"}
 `;
-	return (await run("powershell.exe", [
-		"-NoProfile",
-		"-NonInteractive",
-		"-STA",
-		"-EncodedCommand",
-		Buffer.from(script, "utf16le").toString("base64")
-	], signal)).stdout;
+	const directory = await mkdtemp(join(tmpdir(), "dsh-native-command-"));
+	const scriptPath = join(directory, "associations.ps1");
+	try {
+		await writeFile(scriptPath, `\uFEFF${script}`, "utf8");
+		return (await run("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-STA",
+			"-ExecutionPolicy",
+			"Bypass",
+			"-File",
+			scriptPath
+		], signal, "hidden")).stdout;
+	} finally {
+		await rm(directory, {
+			recursive: true,
+			force: true
+		});
+	}
 }
 //#endregion
 //#region lib/types/types.js
@@ -752,7 +796,7 @@ async function queryFileApplications(path, signal, internals, display) {
 			MAC_APPLICATIONS,
 			target.path,
 			display ? "icons" : "handlers"
-		], signal);
+		], signal, "hidden");
 		const applications = parseMacApplications(JSON.parse(stdout));
 		return display ? dedupeMacApplications(applications) : applications;
 	}
@@ -856,19 +900,19 @@ async function openNativeFileApplication(path, application, signal, internals =
 		"launch",
 		application,
 		path
-	], signal);
+	], signal, "hidden");
 	else await run("open", [
 		"-a",
 		application,
 		path
-	], signal);
+	], signal, "hidden");
 }
 /** Resolve the desktop that owns the file, including Windows applications reached from WSL. */
 async function desktopTarget(path, signal, internals) {
 	signal.throwIfAborted();
 	const platform = internals.platform ?? process.platform;
 	if (platform === "linux" && nativeFileManager(internals) === "explorer") {
-		const translated = await (internals.run ?? runNativeCommand)("wslpath", ["-w", path], signal);
+		const translated = await (internals.run ?? runNativeCommand)("wslpath", ["-w", path], signal, "hidden");
 		signal.throwIfAborted();
 		const windowsPath = translated.stdout.replace(/[\r\n]+$/, "");
 		if (windowsPath === "") throw new Error("wslpath returned no Windows path");

package/lib/types/file-applications-linux.js

@@ -36,11 +36,11 @@ async function desktopFile(root, id, directory = root) {
  * @returns registered applications with the desktop's default marked.
  */
 export async function linuxFileApplications(path, signal, run, env) {
-    const info = await run('gio', ['info', '-a', 'standard::content-type', path], signal);
+    const info = await run('gio', ['info', '-a', 'standard::content-type', path], signal, 'hidden');
     const mime = /standard::content-type:\s*(\S+)/.exec(info.stdout)?.[1];
     if (mime === undefined)
         throw new Error('GIO did not identify the file content type');
-    const result = await run('env', ['LC_ALL=C', 'gio', 'mime', mime], signal);
+    const result = await run('env', ['LC_ALL=C', 'gio', 'mime', mime], signal, 'hidden');
     const preferred = /^Default application.*:\s*(.+\.desktop)\s*$/m.exec(result.stdout)?.[1];
     const ids = [...new Set([...(preferred === undefined ? [] : [preferred]), ...result.stdout.split(/\r?\n/)
                 .filter(line => /^\s+.*\.desktop\s*$/.test(line)).map(line => line.trim())])];

package/lib/types/file-applications-windows.d.ts

@@ -1,7 +1,7 @@
-/** Windows Shell association queries and invocation; paths are encoded data, never PowerShell expressions. */
 import type { NativeCommandRunner } from './runner.ts';
 /**
- * Execute the Windows Shell adapter in a Unicode STA PowerShell process.
+ * Execute the Windows Shell adapter in a Unicode STA PowerShell process; the adapter
+ * source is a private temporary script file, removed once the call settles.
  * @param path - Windows file path, translated by the caller for WSL.
  * @param application - registered handler to invoke; null requests the application list.
  * @param signal - caller cancellation.

package/lib/types/file-applications-windows.js

@@ -1,3 +1,7 @@
+/** Windows Shell association queries and invocation; paths are encoded data, never PowerShell expressions. */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 /** Shell interfaces are declared in their native vtable order; Invoke preserves packaged-app and DDE handling. */
 const WINDOWS_ASSOCIATIONS = String.raw `
 using System;
@@ -38,6 +42,8 @@ public static class DshFileAssociations {
   static extern int SHDefExtractIcon(string path, int index, uint flags, out IntPtr large, out IntPtr small, uint size);
   [DllImport("user32.dll")]
   static extern bool DestroyIcon(IntPtr icon);
+  [DllImport("shlwapi.dll", CharSet = CharSet.Unicode)]
+  static extern int SHLoadIndirectString(string source, StringBuilder output, uint size, IntPtr reserved);
 
   [DllImport("shlwapi.dll", PreserveSig = false)]
   static extern void SHCreateThreadRef(IntPtr count, out IntPtr reference);
@@ -115,12 +121,18 @@ public static class DshFileAssociations {
     var text = new StringBuilder((int)size);
     return AssocQueryString(0, kind, extension, null, text, ref size) == 0 ? text.ToString() : null;
   }
-  static string IconData(IHandler handler) {
+  // Resolve a packaged application's indirect icon reference, for example
+  // @{Microsoft.WindowsNotepad_...?ms-resource://.../NotepadAppList.png}, to
+  // the resource file the Shell would draw; an unresolved reference is null.
+  static string ResolveIndirectIcon(string source) {
+    var output = new StringBuilder(1024);
+    return SHLoadIndirectString(source, output, (uint)output.Capacity, IntPtr.Zero) == 0 ? output.ToString() : null;
+  }
+  // Read one icon source into a 32px PNG: an image file directly, otherwise the
+  // resource the Shell extracts at the given index. A missing resource is null.
+  static string PngFromIconSource(string source, int index) {
     IntPtr large = IntPtr.Zero, small = IntPtr.Zero;
     try {
-      string source; int index;
-      handler.GetIconLocation(out source, out index);
-      source = Environment.ExpandEnvironmentVariables(source);
       if (Path.GetExtension(source).Equals(".png", StringComparison.OrdinalIgnoreCase)) {
         using (var original = Image.FromFile(source))
         using (var resized = new Bitmap(original, new Size(32, 32)))
@@ -144,6 +156,26 @@ public static class DshFileAssociations {
       if (small != IntPtr.Zero) DestroyIcon(small);
     }
   }
+  // Best-effort fallback: some handlers return their executable path from GetName, but a
+  // packaged handler's name may be an AUMID or family name, which extracts no icon.
+  static string IconData(IHandler handler, string id) {
+    string source = null; int index = 0;
+    try { handler.GetIconLocation(out source, out index); } catch (Exception) {
+      // A handler without a drawable icon location falls back to its name.
+    }
+    if (!String.IsNullOrEmpty(source)) {
+      source = Environment.ExpandEnvironmentVariables(source);
+      if (source.StartsWith("@{", StringComparison.Ordinal) && source.EndsWith("}", StringComparison.Ordinal)) {
+        var resolved = ResolveIndirectIcon(source);
+        if (!String.IsNullOrEmpty(resolved)) source = resolved;
+      }
+      var icon = PngFromIconSource(source, index);
+      if (icon != null) return icon;
+    }
+    return String.IsNullOrEmpty(id) || String.Equals(id, source, StringComparison.OrdinalIgnoreCase)
+      ? null
+      : PngFromIconSource(id, 0);
+  }
   static void Visit(string path, Action<IHandler> visit) {
     var extension = Path.GetExtension(path);
     if (extension.Length == 0) return;
@@ -169,7 +201,7 @@ public static class DshFileAssociations {
       string id, name;
       handler.GetName(out id); handler.GetUIName(out name);
       if (!seen.Add(id)) return;
-      apps.Add(new Application { id = id, name = name, icon = IconData(handler),
+      apps.Add(new Application { id = id, name = name, icon = IconData(handler, id),
         @default = String.Equals(id, executable, StringComparison.OrdinalIgnoreCase) || String.Equals(id, appId, StringComparison.OrdinalIgnoreCase) });
     });
     return apps.ToArray();
@@ -201,7 +233,8 @@ public static class DshFileAssociations {
   }
 }`;
 /**
- * Execute the Windows Shell adapter in a Unicode STA PowerShell process.
+ * Execute the Windows Shell adapter in a Unicode STA PowerShell process; the adapter
+ * source is a private temporary script file, removed once the call settles.
  * @param path - Windows file path, translated by the caller for WSL.
  * @param application - registered handler to invoke; null requests the application list.
  * @param signal - caller cancellation.
@@ -220,9 +253,21 @@ $path = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPa
 $application = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedApplication}'))
 ${application === null ? 'ConvertTo-Json -InputObject @([DshFileAssociations]::List($path)) -Depth 4 -Compress' : '[DshFileAssociations]::Open($path, $application)'}
 `;
-    const result = await run('powershell.exe', [
-        '-NoProfile', '-NonInteractive', '-STA', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64'),
-    ], signal);
-    return result.stdout;
+    // The script travels as a file, not as command-line data: -EncodedCommand grew with the
+    // embedded C# and overflowed the 32767-character CreateProcess limit for long paths.
+    // PowerShell 5.1 decodes a -File script as ANSI unless it carries a BOM; the BOM keeps
+    // the embedded UTF-8 source intact.
+    const directory = await mkdtemp(join(tmpdir(), 'dsh-native-command-'));
+    const scriptPath = join(directory, 'associations.ps1');
+    try {
+        await writeFile(scriptPath, `\uFEFF${script}`, 'utf8');
+        const result = await run('powershell.exe', [
+            '-NoProfile', '-NonInteractive', '-STA', '-ExecutionPolicy', 'Bypass', '-File', scriptPath,
+        ], signal, 'hidden');
+        return result.stdout;
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
 }
 //# sourceMappingURL=file-applications-windows.js.map

package/lib/types/file-applications.js

@@ -64,7 +64,7 @@ async function queryFileApplications(path, signal, internals, display) {
     if (target.platform === 'linux')
         return linuxFileApplications(path, signal, run, internals.env ?? process.env);
     if (target.platform === 'darwin') {
-        const { stdout } = await run('osascript', ['-l', 'JavaScript', '-e', MAC_APPLICATIONS, target.path, display ? 'icons' : 'handlers'], signal);
+        const { stdout } = await run('osascript', ['-l', 'JavaScript', '-e', MAC_APPLICATIONS, target.path, display ? 'icons' : 'handlers'], signal, 'hidden');
         const applications = parseMacApplications(JSON.parse(stdout));
         return display ? dedupeMacApplications(applications) : applications;
     }
@@ -170,16 +170,16 @@ export async function openNativeFileApplication(path, application, signal, inter
     if (!apps.some(app => app.id === application))
         throw new Error('Application is not registered for this file');
     if (target.platform === 'linux')
-        await run('gio', ['launch', application, path], signal);
+        await run('gio', ['launch', application, path], signal, 'hidden');
     else
-        await run('open', ['-a', application, path], signal);
+        await run('open', ['-a', application, path], signal, 'hidden');
 }
 /** Resolve the desktop that owns the file, including Windows applications reached from WSL. */
 async function desktopTarget(path, signal, internals) {
     signal.throwIfAborted();
     const platform = internals.platform ?? process.platform;
     if (platform === 'linux' && nativeFileManager(internals) === 'explorer') {
-        const translated = await (internals.run ?? runNativeCommand)('wslpath', ['-w', path], signal);
+        const translated = await (internals.run ?? runNativeCommand)('wslpath', ['-w', path], signal, 'hidden');
         signal.throwIfAborted();
         const windowsPath = translated.stdout.replace(/[\r\n]+$/, '');
         if (windowsPath === '')

package/lib/types/path-opener.js

@@ -38,7 +38,7 @@ async function openInBrowser(path, signal, platform, run, env) {
     if (platform === 'darwin') {
         let bundle;
         try {
-            const { stdout } = await run('defaults', ['read', 'com.apple.LaunchServices/com.apple.launchservices.secure'], signal);
+            const { stdout } = await run('defaults', ['read', 'com.apple.LaunchServices/com.apple.launchservices.secure'], signal, 'hidden');
             bundle = macBundleForHttps(stdout);
         }
         catch {
@@ -48,7 +48,7 @@ async function openInBrowser(path, signal, platform, run, env) {
         }
         if (bundle === undefined)
             return false;
-        await run('open', ['-b', bundle, path], signal);
+        await run('open', ['-b', bundle, path], signal, 'hidden');
         return true;
     }
     if (platform === 'linux') {
@@ -57,7 +57,7 @@ async function openInBrowser(path, signal, platform, run, env) {
         const browser = env.BROWSER;
         if (browser === undefined || browser === '')
             return false;
-        await run(browser, [path], signal);
+        await run(browser, [path], signal, 'hidden');
         return true;
     }
     // Windows names no browser without reading the UserChoice registry, and its
@@ -112,7 +112,8 @@ function explorerTarget(windowsPath) {
  */
 async function runExplorer(args, signal, run) {
     try {
-        await run('explorer.exe', args, signal);
+        // SW_HIDE also hides Explorer's folder window, not just console windows.
+        await run('explorer.exe', args, signal, 'visible');
     }
     catch (error) {
         signal.throwIfAborted();
@@ -133,7 +134,7 @@ async function openWindowsPath(path, signal, run) {
 }
 /** Translate a WSL path before handing it to the Windows desktop. */
 async function openWslPath(path, signal, run) {
-    const translated = await run('wslpath', ['-w', path], signal);
+    const translated = await run('wslpath', ['-w', path], signal, 'hidden');
     signal.throwIfAborted();
     const windowsPath = translated.stdout.replace(/[\r\n]+$/, '');
     if (windowsPath === '')
@@ -150,7 +151,7 @@ async function openNativePathWithIntent(path, signal, intent, internals = {}) {
         && await openInBrowser(path, signal, platform, run, env))
         return;
     if (platform === 'darwin') {
-        await run('open', intent === 'text-editor' ? ['-t', path] : [path], signal);
+        await run('open', intent === 'text-editor' ? ['-t', path] : [path], signal, 'hidden');
         return;
     }
     if (platform === 'win32') {
@@ -162,7 +163,7 @@ async function openNativePathWithIntent(path, signal, intent, internals = {}) {
             await openWslPath(path, signal, run);
             return;
         }
-        await run('xdg-open', [path], signal);
+        await run('xdg-open', [path], signal, 'hidden');
         return;
     }
     throw new Error(`native path opener is unsupported on ${platform}`);
@@ -243,13 +244,13 @@ export async function revealNativePath(path, signal, internals = {}) {
     const run = internals.run ?? runNativeCommand;
     const manager = nativeFileManager({ ...internals, platform });
     if (manager === 'finder') {
-        await run('open', ['-R', path], signal);
+        await run('open', ['-R', path], signal, 'hidden');
         return;
     }
     if (manager === 'explorer') {
         let windowsPath = path;
         if (platform === 'linux') {
-            const translated = await run('wslpath', ['-w', path], signal);
+            const translated = await run('wslpath', ['-w', path], signal, 'hidden');
             signal.throwIfAborted();
             windowsPath = translated.stdout.replace(/[\r\n]+$/, '');
             if (windowsPath === '')
@@ -259,7 +260,7 @@ export async function revealNativePath(path, signal, internals = {}) {
         return;
     }
     if (manager === 'directory') {
-        await run('xdg-open', [dirname(path)], signal);
+        await run('xdg-open', [dirname(path)], signal, 'hidden');
         return;
     }
     throw new Error(`native file manager is unsupported on ${platform}`);

package/lib/types/runner.d.ts

@@ -3,15 +3,17 @@
  * @module @deepseek-ai/dsh-native-command/runner
  */
 /** Testable command boundary; native implementations never invoke a shell. */
-export type NativeCommandRunner = (command: string, args: readonly string[], signal: AbortSignal) => Promise<{
+export type NativeCommandRunner = (command: string, args: readonly string[], signal: AbortSignal, window: 'hidden' | 'visible') => Promise<{
     stdout: string;
     stderr: string;
 }>;
 /**
- * Run a host command with utf8 stdio, abort propagation, and Windows hide.
+ * Run a host command with utf8 stdio, abort propagation, and explicit GUI visibility.
  * @param command - executable path or PATH name.
  * @param args - argv (never a shell string).
  * @param signal - caller/connection lifetime; abort terminates the child.
+ * @param window - Windows startup visibility: `hidden` for background commands,
+ * `visible` for GUI launchers. Ignored on other platforms.
  * @returns captured stdout/stderr on exit 0.
  */
 export declare const runNativeCommand: NativeCommandRunner;

package/lib/types/runner.js

@@ -4,14 +4,16 @@
  */
 import { execFile } from 'node:child_process';
 /**
- * Run a host command with utf8 stdio, abort propagation, and Windows hide.
+ * Run a host command with utf8 stdio, abort propagation, and explicit GUI visibility.
  * @param command - executable path or PATH name.
  * @param args - argv (never a shell string).
  * @param signal - caller/connection lifetime; abort terminates the child.
+ * @param window - Windows startup visibility: `hidden` for background commands,
+ * `visible` for GUI launchers. Ignored on other platforms.
  * @returns captured stdout/stderr on exit 0.
  */
-export const runNativeCommand = (command, args, signal) => new Promise((resolve, reject) => {
-    execFile(command, [...args], { encoding: 'utf8', signal, windowsHide: true }, (error, stdout, stderr) => {
+export const runNativeCommand = (command, args, signal, window) => new Promise((resolve, reject) => {
+    execFile(command, [...args], { encoding: 'utf8', signal, windowsHide: window === 'hidden' }, (error, stdout, stderr) => {
         if (error !== null) {
             const failure = Object.assign(new Error(error.message, { cause: error }), {
                 code: error.code,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-native-command",
   "description": "Host-native command and path-opening utilities with shell-free execution, cancellation, desktop detection, and WSL handoff",
-  "version": "0.1.7-rc.1",
+  "version": "0.2.0-rc.1",
   "publishConfig": {
     "access": "public"
   },