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

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: 18e2f1f3798079dd
+  zh: 6f5579374e208624
+/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: 3a499bda33e33102
+  zh: d01abbf863810607
+/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: b16da99b2ed73bfd
+  zh: 5e806c31a6296366
+/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

@@ -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.
 
 -----
 
@@ -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

@@ -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 目录。
 
 -----
 
@@ -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,8 +1,8 @@
 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.
@@ -431,6 +431,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 +472,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 +551,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 +586,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 +631,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 +663,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 +681,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)).stdout;
+	} finally {
+		await rm(directory, {
+			recursive: true,
+			force: true
+		});
+	}
 }
 //#endregion
 //#region lib/types/types.js

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);
+        return result.stdout;
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
 }
 //# sourceMappingURL=file-applications-windows.js.map

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.1.7-rc.2",
   "publishConfig": {
     "access": "public"
   },