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

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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:
 #   pnpm run verify-translation-pairing --write packages/util/native-command/README.md
-README.md: 23df6d784aae1a5a911b556a3d70bae7971bd566
-README.zh.md: e8548777191d1433188712c42797d4a902314f64
+README.md: c9e1f3fd936093bcad334390704b97630f7acfc8
+README.zh.md: 2c6feadbb8e09391ab5f112e0129b669f6c33127

package/README.md

@@ -45,9 +45,9 @@ The `NativeCommandRunner` type is the injectable command boundary for host integ
 
 ### Opening a Host path
 
-`openNativePath(path, signal)` hands a path to the default application and prefers the named default browser for HTML and SVG where the platform can identify one. `openNativeAssociatedPath(path, signal)` always uses the file-type association, without a browser override. `openNativeTextFile(path, signal)` selects text-editor intent; on macOS it uses `open -t`. WSL paths are translated with `wslpath -w` before the Windows desktop receives them. `canOpenNativePath()` reports whether the current Host plausibly has a desktop target.
+`openNativePath(path, signal)` hands a path to the default application and prefers the named default browser for HTML and SVG where the platform can identify one. `openNativeAssociatedPath(path, signal)` always uses the file-type association, without a browser override. `openNativeTextFile(path, signal)` selects text-editor intent; on macOS it uses `open -t`. Windows hands every intent to Explorer, so the shell's own default-application resolution — the one a double-click uses — picks the application; Explorer receives the target as an encoded file URI and its exit code 1 counts as a delegated handoff, while cancellation, missing executables, and other exit codes still reject. This acknowledgement does not prove that an application opened the file. WSL paths are translated with `wslpath -w` before the Windows desktop receives them. `canOpenNativePath()` reports whether the current Host plausibly has a desktop target.
 
-`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 a desktop window selected the file.
+`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.
 
@@ -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 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>
 ### Dev Note

package/README.zh.md

@@ -45,9 +45,9 @@ const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], s
 
 ### 打开 Host 路径
 
-`openNativePath(path, signal)` 将路径交给默认应用；平台能够确定默认浏览器时，HTML 与 SVG 会优先交给该浏览器。`openNativeAssociatedPath(path, signal)` 始终使用文件类型关联，不覆盖为浏览器。`openNativeTextFile(path, signal)` 选择文本编辑器意图；macOS 使用 `open -t`。WSL 路径先通过 `wslpath -w` 转换，再交给 Windows 桌面。`canOpenNativePath()` 报告当前 Host 是否可能具备桌面目标。
+`openNativePath(path, signal)` 将路径交给默认应用；平台能够确定默认浏览器时，HTML 与 SVG 会优先交给该浏览器。`openNativeAssociatedPath(path, signal)` 始终使用文件类型关联，不覆盖为浏览器。`openNativeTextFile(path, signal)` 选择文本编辑器意图；macOS 使用 `open -t`。Windows 将每种意图都交给 Explorer，由 shell 自身的默认应用解析（即双击所走的那条）选择应用；Explorer 收到的是编码后的文件 URI，其退出码 1 按已转交请求处理，取消、找不到可执行文件和其他退出码仍然报错。该确认不能证明应用已打开文件。WSL 路径先通过 `wslpath -w` 转换，再交给 Windows 桌面。`canOpenNativePath()` 报告当前 Host 是否可能具备桌面目标。
 
-`revealNativePath(path, signal)` 在 Finder 或文件资源管理器中选中文件，包含 WSL 路径转换；在桌面 Linux 上通过 `xdg-open` 打开上层目录。`nativeFileManager()` 标识该操作，供 UI 根据 Host 选择文案；桌面是否可用仍由独立的 `canOpenNativePath()` 检查决定。调用方必须先授权绝对文件路径，再执行操作。平台分派由注入运行器的测试覆盖；原生桌面验证由对应平台负责。 Explorer 接收独立参数中的编码文件 URI。退出码 1 按已转交请求处理；取消、找不到可执行文件和其他退出码仍然报错。该确认不能证明桌面窗口已选中文件。
+`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 目录。
 
@@ -109,6 +109,7 @@ Linux 的关联查询和指定应用启动需要 GIO。缺少原生命令时查
 这些限制说明本运行器何时不是合适的工具。它们是当前包约束，不是任务积压。
 
 - 命令输出受 Node 的 `execFile` 缓冲上限约束，超过上限时拒绝结果。流式输出由 subprocess 能力处理。
+- 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

@@ -44,7 +44,10 @@ const runNativeCommand = (command, args, signal) => new Promise((resolve, reject
 * The default intent prefers the default browser for documents it renders when
 * the platform can name one, then falls back to the default application. WSL
 * translates every path for the Windows desktop instead of assuming a Linux
-* GUI. The text-editor intent never consults the browser.
+* GUI. The text-editor intent never consults the browser. Windows hands every
+* intent to Explorer: the shell's own default-application resolution, the one
+* a double-click uses, selects the application, while a process that resolves
+* the association itself reads a narrower record and reports none.
 * @module @deepseek-ai/dsh-native-command/path-opener
 */
 /** Documents a browser renders, as opposed to ones an editor merely edits. */
@@ -95,10 +98,6 @@ async function openInBrowser(path, signal, platform, run, env) {
 	}
 	return false;
 }
-/** PowerShell single-quoted literal (doubles embedded quotes). */
-function powershellLiteral(path) {
-	return `'${path.replace(/'/g, "''")}'`;
-}
 /** Whether one environment marker is set to a non-empty value. */
 function present(value) {
 	return value !== void 0 && value !== "";
@@ -109,13 +108,53 @@ function isWsl(internals) {
 	if (present(env.WSL_DISTRO_NAME) || present(env.WSL_INTEROP)) return true;
 	return (internals.osRelease ?? release()).toLowerCase().includes("microsoft");
 }
-/** Open one Windows-resolvable path through its registered desktop application. */
+/**
+* Encode one Windows path as the target Explorer can receive intact.
+*
+* Explorer parses its own command line and splits fields at commas and equals
+* signs, so a raw path loses everything after the first separator and the shell
+* opens a different target without reporting it; both separators are escaped.
+* Nothing else is: Explorer rejects percent-encoded non-ASCII in a file URI and
+* opens the user's Documents folder instead, while it resolves the literal
+* characters, so Node's non-ASCII escapes are decoded back and its ASCII escapes
+* stand. Node resolves the path before encoding it, so a verbatim `\\?\` or
+* `\\?\UNC\` prefix reaches Explorer as the ordinary drive or UNC URI; a `\\.\`
+* device path keeps that same UNC handling and names a device rather than a
+* shell item, which this opener does not open.
+* @param windowsPath - path already translated for the Windows desktop.
+* @returns the target for an open, or the object of a `/select,` reveal.
+*/
+function explorerTarget(windowsPath) {
+	return pathToFileURL(windowsPath, { windows: true }).href.replace(/(?:%[89A-F][0-9A-F])+/gi, (escaped) => decodeURIComponent(escaped)).replaceAll(",", "%2C").replaceAll("=", "%3D");
+}
+/**
+* Hand one target to Explorer, accepting its delegated-handoff exit code.
+*
+* Explorer exits 1 after handing the request to the desktop process already
+* running, so exit 1 means the shell took it. Every other failure still
+* rejects, and cancellation wins over a delegate's exit 1.
+* @param args - Explorer argv: the encoded target alone to open it, or `/select,<encoded target>` to reveal it.
+* @param signal - caller lifetime; abort terminates the command.
+* @param run - shell-free command runner.
+* @throws The runner's failure unless it is Explorer's delegate exit 1.
+*/
+async function runExplorer(args, signal, run) {
+	try {
+		await run("explorer.exe", args, signal);
+	} catch (error) {
+		signal.throwIfAborted();
+		if (!(error instanceof Error) || !("code" in error) || error.code !== 1) throw error;
+	}
+}
+/**
+* Open one Windows-resolvable path through Explorer, the shell that owns the
+* default-application resolution a double-click uses.
+* @param path - Windows-resolvable path; Explorer receives its encoded file URI as one argv element, never a command string.
+* @param signal - caller lifetime; abort terminates the command.
+* @param run - shell-free command runner.
+*/
 async function openWindowsPath(path, signal, run) {
-	await run("powershell.exe", [
-		"-NoProfile",
-		"-Command",
-		`Invoke-Item -LiteralPath ${powershellLiteral(path)}`
-	], signal);
+	await runExplorer([explorerTarget(path)], signal, run);
 }
 /** Translate a WSL path before handing it to the Windows desktop. */
 async function openWslPath(path, signal, run) {
@@ -236,13 +275,7 @@ async function revealNativePath(path, signal, internals = {}) {
 			windowsPath = translated.stdout.replace(/[\r\n]+$/, "");
 			if (windowsPath === "") throw new Error("wslpath returned no Windows path");
 		}
-		const target = pathToFileURL(windowsPath, { windows: true }).href.replaceAll(",", "%2C");
-		try {
-			await run("explorer.exe", ["/select,", target], signal);
-		} catch (error) {
-			signal.throwIfAborted();
-			if (!(error instanceof Error) || !("code" in error) || error.code !== 1) throw error;
-		}
+		await runExplorer(["/select,", explorerTarget(windowsPath)], signal, run);
 		return;
 	}
 	if (manager === "directory") {

package/lib/types/path-opener.d.ts

@@ -5,7 +5,10 @@
  * The default intent prefers the default browser for documents it renders when
  * the platform can name one, then falls back to the default application. WSL
  * translates every path for the Windows desktop instead of assuming a Linux
- * GUI. The text-editor intent never consults the browser.
+ * GUI. The text-editor intent never consults the browser. Windows hands every
+ * intent to Explorer: the shell's own default-application resolution, the one
+ * a double-click uses, selects the application, while a process that resolves
+ * the association itself reads a narrower record and reports none.
  * @module @deepseek-ai/dsh-native-command/path-opener
  */
 import { type NativeCommandRunner } from './runner.ts';

package/lib/types/path-opener.js

@@ -5,7 +5,10 @@
  * The default intent prefers the default browser for documents it renders when
  * the platform can name one, then falls back to the default application. WSL
  * translates every path for the Windows desktop instead of assuming a Linux
- * GUI. The text-editor intent never consults the browser.
+ * GUI. The text-editor intent never consults the browser. Windows hands every
+ * intent to Explorer: the shell's own default-application resolution, the one
+ * a double-click uses, selects the application, while a process that resolves
+ * the association itself reads a narrower record and reports none.
  * @module @deepseek-ai/dsh-native-command/path-opener
  */
 import { release as osRelease } from 'node:os';
@@ -61,10 +64,6 @@ async function openInBrowser(path, signal, platform, run, env) {
     // .html association is the browser in the ordinary case.
     return false;
 }
-/** PowerShell single-quoted literal (doubles embedded quotes). */
-function powershellLiteral(path) {
-    return `'${path.replace(/'/g, "''")}'`;
-}
 /** Whether one environment marker is set to a non-empty value. */
 function present(value) {
     return value !== undefined && value !== '';
@@ -76,13 +75,61 @@ function isWsl(internals) {
         return true;
     return (internals.osRelease ?? osRelease()).toLowerCase().includes('microsoft');
 }
-/** Open one Windows-resolvable path through its registered desktop application. */
+/**
+ * Encode one Windows path as the target Explorer can receive intact.
+ *
+ * Explorer parses its own command line and splits fields at commas and equals
+ * signs, so a raw path loses everything after the first separator and the shell
+ * opens a different target without reporting it; both separators are escaped.
+ * Nothing else is: Explorer rejects percent-encoded non-ASCII in a file URI and
+ * opens the user's Documents folder instead, while it resolves the literal
+ * characters, so Node's non-ASCII escapes are decoded back and its ASCII escapes
+ * stand. Node resolves the path before encoding it, so a verbatim `\\?\` or
+ * `\\?\UNC\` prefix reaches Explorer as the ordinary drive or UNC URI; a `\\.\`
+ * device path keeps that same UNC handling and names a device rather than a
+ * shell item, which this opener does not open.
+ * @param windowsPath - path already translated for the Windows desktop.
+ * @returns the target for an open, or the object of a `/select,` reveal.
+ */
+function explorerTarget(windowsPath) {
+    const href = pathToFileURL(windowsPath, { windows: true }).href;
+    // A run of escapes whose every byte starts above ASCII is one non-ASCII character.
+    return href
+        .replace(/(?:%[89A-F][0-9A-F])+/gi, escaped => decodeURIComponent(escaped))
+        .replaceAll(',', '%2C')
+        .replaceAll('=', '%3D');
+}
+/**
+ * Hand one target to Explorer, accepting its delegated-handoff exit code.
+ *
+ * Explorer exits 1 after handing the request to the desktop process already
+ * running, so exit 1 means the shell took it. Every other failure still
+ * rejects, and cancellation wins over a delegate's exit 1.
+ * @param args - Explorer argv: the encoded target alone to open it, or `/select,<encoded target>` to reveal it.
+ * @param signal - caller lifetime; abort terminates the command.
+ * @param run - shell-free command runner.
+ * @throws The runner's failure unless it is Explorer's delegate exit 1.
+ */
+async function runExplorer(args, signal, run) {
+    try {
+        await run('explorer.exe', args, signal);
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        // Explorer can exit 1 after delegating to the existing desktop process.
+        if (!(error instanceof Error) || !('code' in error) || error.code !== 1)
+            throw error;
+    }
+}
+/**
+ * Open one Windows-resolvable path through Explorer, the shell that owns the
+ * default-application resolution a double-click uses.
+ * @param path - Windows-resolvable path; Explorer receives its encoded file URI as one argv element, never a command string.
+ * @param signal - caller lifetime; abort terminates the command.
+ * @param run - shell-free command runner.
+ */
 async function openWindowsPath(path, signal, run) {
-    await run('powershell.exe', [
-        '-NoProfile',
-        '-Command',
-        `Invoke-Item -LiteralPath ${powershellLiteral(path)}`,
-    ], signal);
+    await runExplorer([explorerTarget(path)], signal, run);
 }
 /** Translate a WSL path before handing it to the Windows desktop. */
 async function openWslPath(path, signal, run) {
@@ -208,17 +255,7 @@ export async function revealNativePath(path, signal, internals = {}) {
             if (windowsPath === '')
                 throw new Error('wslpath returned no Windows path');
         }
-        // Explorer parses commas itself; a file URI preserves commas and whitespace in the path.
-        const target = pathToFileURL(windowsPath, { windows: true }).href.replaceAll(',', '%2C');
-        try {
-            await run('explorer.exe', ['/select,', target], signal);
-        }
-        catch (error) {
-            signal.throwIfAborted();
-            // Explorer can exit 1 after delegating to the existing desktop process.
-            if (!(error instanceof Error) || !('code' in error) || error.code !== 1)
-                throw error;
-        }
+        await runExplorer(['/select,', explorerTarget(windowsPath)], signal, run);
         return;
     }
     if (manager === 'directory') {

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-alpha.1",
+  "version": "0.1.7-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -32,9 +32,9 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.3"
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.3"
+    "@deepseek-ai/cordis": "~4.0.4"
   }
 }