@deepseek-ai/dsh-native-command 0.1.3-alpha.2 → 0.1.5-alpha.2

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: 06baa6d631198e42c6de3e20c8a0bd562564b779
-README.zh.md: 6df6ee25e32e5f7290af1c4af580fe108a0d3b9f
+README.md: b0b1963a97c6d528c123d4900db529bd3dc38332
+README.zh.md: 6a245e3473a4e4dd9944dc53898e04be2fcba2e4

package/README.md

@@ -47,6 +47,8 @@ The `NativeCommandRunner` type is the injectable command boundary for host integ
 
 `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. `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.
 
+`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.
+
 -----
 
 <a id="understand-the-implementation"></a>

package/README.zh.md

@@ -47,6 +47,8 @@ const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], s
 
 `openNativePath(path, signal)` 将路径交给默认应用；平台能够确定默认浏览器时，HTML 与 SVG 会优先交给该浏览器。`openNativeTextFile(path, signal)` 选择文本编辑器意图；macOS 使用 `open -t`。WSL 路径先通过 `wslpath -w` 转换，再交给 Windows 桌面。`canOpenNativePath()` 报告当前 Host 是否可能具备桌面目标。
 
+`revealNativePath(path, signal)` 在 Finder 或文件资源管理器中选中文件，包含 WSL 路径转换；在桌面 Linux 上通过 `xdg-open` 打开上层目录。`nativeFileManager()` 标识该操作，供 UI 根据 Host 选择文案；桌面是否可用仍由独立的 `canOpenNativePath()` 检查决定。调用方必须先授权绝对文件路径，再执行操作。平台分派由注入运行器的测试覆盖；原生桌面验证由对应平台负责。 Explorer 接收独立参数中的编码文件 URI。退出码 1 按已转交请求处理；取消、找不到可执行文件和其他退出码仍然报错。该确认不能证明桌面窗口已选中文件。
+
 -----
 
 <a id="understand-the-implementation"></a>

package/lib/index.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import { release } from "node:os";
-import { extname } from "node:path";
+import { dirname, extname } from "node:path";
+import { pathToFileURL } from "node:url";
 //#region lib/types/runner.js
 /**
 * Shared no-shell `execFile` runner for host-native OS integrations.
@@ -186,5 +187,58 @@ function openNativePath(path, signal, internals = {}) {
 function openNativeTextFile(path, signal, internals = {}) {
 	return openNativePathWithIntent(path, signal, "text-editor", internals);
 }
+/**
+* Identify the native file-manager action without inspecting the browser's platform.
+* @param internals - platform and WSL facts.
+* @returns the supported file-manager action, or null on unsupported platforms.
+*/
+function nativeFileManager(internals = {}) {
+	const platform = internals.platform ?? process.platform;
+	if (platform === "darwin") return "finder";
+	if (platform === "win32" || platform === "linux" && isWsl(internals)) return "explorer";
+	return platform === "linux" ? "directory" : null;
+}
+/**
+* Reveal a file in Finder or Explorer, or open its parent in the Linux default file manager.
+* @param path - absolute file path already authorized by the caller.
+* @param signal - caller lifetime; abort terminates the native command.
+* @param internals - platform, environment, and command runner for adapter tests.
+* @returns after command completion; Explorer exit 1 is accepted as a delegated handoff, not proof of selection.
+*/
+async function revealNativePath(path, signal, internals = {}) {
+	signal.throwIfAborted();
+	const platform = internals.platform ?? process.platform;
+	const run = internals.run ?? runNativeCommand;
+	const manager = nativeFileManager({
+		...internals,
+		platform
+	});
+	if (manager === "finder") {
+		await run("open", ["-R", path], signal);
+		return;
+	}
+	if (manager === "explorer") {
+		let windowsPath = path;
+		if (platform === "linux") {
+			const translated = await run("wslpath", ["-w", path], signal);
+			signal.throwIfAborted();
+			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;
+		}
+		return;
+	}
+	if (manager === "directory") {
+		await run("xdg-open", [dirname(path)], signal);
+		return;
+	}
+	throw new Error(`native file manager is unsupported on ${platform}`);
+}
 //#endregion
-export { canOpenNativePath, openNativePath, openNativeTextFile, runNativeCommand };
+export { canOpenNativePath, nativeFileManager, openNativePath, openNativeTextFile, revealNativePath, runNativeCommand };

package/lib/types/index.d.ts

@@ -4,6 +4,6 @@
  */
 export { runNativeCommand } from './runner.ts';
 export type { NativeCommandRunner } from './runner.ts';
-export { canOpenNativePath, openNativePath, openNativeTextFile, } from './path-opener.ts';
-export type { PathOpenerInternals, PathOpenerRunner, } from './path-opener.ts';
+export { canOpenNativePath, nativeFileManager, revealNativePath, openNativePath, openNativeTextFile, } from './path-opener.ts';
+export type { NativeFileManager, PathOpenerInternals, PathOpenerRunner, } from './path-opener.ts';
 //# sourceMappingURL=index.d.ts.map

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

@@ -48,4 +48,20 @@ export declare function openNativePath(path: string, signal: AbortSignal, intern
  * @param internals - Platform and runner hooks for deterministic tests.
  */
 export declare function openNativeTextFile(path: string, signal: AbortSignal, internals?: PathOpenerInternals): Promise<void>;
+/** File-manager behavior available on the serving Host, including WSL's Windows desktop. */
+export type NativeFileManager = 'finder' | 'explorer' | 'directory';
+/**
+ * Identify the native file-manager action without inspecting the browser's platform.
+ * @param internals - platform and WSL facts.
+ * @returns the supported file-manager action, or null on unsupported platforms.
+ */
+export declare function nativeFileManager(internals?: PathOpenerInternals): NativeFileManager | null;
+/**
+ * Reveal a file in Finder or Explorer, or open its parent in the Linux default file manager.
+ * @param path - absolute file path already authorized by the caller.
+ * @param signal - caller lifetime; abort terminates the native command.
+ * @param internals - platform, environment, and command runner for adapter tests.
+ * @returns after command completion; Explorer exit 1 is accepted as a delegated handoff, not proof of selection.
+ */
+export declare function revealNativePath(path: string, signal: AbortSignal, internals?: PathOpenerInternals): Promise<void>;
 //# sourceMappingURL=path-opener.d.ts.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.3-alpha.2",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },