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

package/lib/types/path-opener.js

@@ -0,0 +1,230 @@
+/**
+ * Cross-platform native path and text-document openers for Host UI
+ * integrations.
+ *
+ * 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.
+ * @module @deepseek-ai/dsh-native-command/path-opener
+ */
+import { release as osRelease } from 'node:os';
+import { dirname, extname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { runNativeCommand } from "./runner.js";
+/** Documents a browser renders, as opposed to ones an editor merely edits. */
+const BROWSER_DOCUMENTS = new Set(['.html', '.htm', '.xhtml', '.svg']);
+/**
+ * The macOS bundle registered for `https` — the default browser, as
+ * LaunchServices records it. The nested version dict is stripped first
+ * because it carries its own `LSHandlerRoleAll`.
+ */
+function macBundleForHttps(plist) {
+    const stripped = plist.replace(/LSHandlerPreferredVersions\s*=\s*\{[^}]*\};/g, '');
+    const block = /\{[^{}]*LSHandlerURLScheme\s*=\s*"?https"?;[^{}]*\}/.exec(stripped)?.[0];
+    if (block === undefined)
+        return undefined;
+    return /LSHandlerRoleAll\s*=\s*"?([\w.-]+)"?;/.exec(block)?.[1];
+}
+/**
+ * Open one browser-renderable document with the default browser.
+ * @returns true when a browser took it; false when this platform cannot name
+ * one, or naming it failed — the caller then uses the default application.
+ */
+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);
+            bundle = macBundleForHttps(stdout);
+        }
+        catch {
+            // No LaunchServices record (a fresh account never changed a default):
+            // the content-type handler is then the system's own choice anyway.
+            return false;
+        }
+        if (bundle === undefined)
+            return false;
+        await run('open', ['-b', bundle, path], signal);
+        return true;
+    }
+    if (platform === 'linux') {
+        // $BROWSER is the portable convention; desktop-entry resolution through
+        // xdg-settings needs a launcher this package has no business shipping.
+        const browser = env.BROWSER;
+        if (browser === undefined || browser === '')
+            return false;
+        await run(browser, [path], signal);
+        return true;
+    }
+    // Windows names no browser without reading the UserChoice registry, and its
+    // .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 !== '';
+}
+/** Distinguish WSL from desktop Linux using its process and kernel markers. */
+function isWsl(internals) {
+    const env = internals.env ?? process.env;
+    if (present(env.WSL_DISTRO_NAME) || present(env.WSL_INTEROP))
+        return true;
+    return (internals.osRelease ?? osRelease()).toLowerCase().includes('microsoft');
+}
+/** Open one Windows-resolvable path through its registered desktop application. */
+async function openWindowsPath(path, signal, run) {
+    await run('powershell.exe', [
+        '-NoProfile',
+        '-Command',
+        `Invoke-Item -LiteralPath ${powershellLiteral(path)}`,
+    ], signal);
+}
+/** 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);
+    signal.throwIfAborted();
+    const windowsPath = translated.stdout.replace(/[\r\n]+$/, '');
+    if (windowsPath === '')
+        throw new Error('wslpath returned no Windows path');
+    await openWindowsPath(windowsPath, signal, run);
+}
+/** Dispatch one shell-free platform command for the requested open intent. */
+async function openNativePathWithIntent(path, signal, intent, internals = {}) {
+    const platform = internals.platform ?? process.platform;
+    const run = internals.run ?? runNativeCommand;
+    const env = internals.env ?? process.env;
+    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);
+        return;
+    }
+    if (platform === 'win32') {
+        await openWindowsPath(path, signal, run);
+        return;
+    }
+    if (platform === 'linux') {
+        if (wsl) {
+            await openWslPath(path, signal, run);
+            return;
+        }
+        await run('xdg-open', [path], signal);
+        return;
+    }
+    throw new Error(`native path opener is unsupported on ${platform}`);
+}
+/**
+ * Whether {@link openNativePath} plausibly reaches a desktop on this host.
+ *
+ * macOS and Windows always carry a desktop opener; Linux does when it is WSL
+ * (the Windows desktop takes the path) or a display server is announced.
+ * A headless or containerised Linux host answers false, which is what lets a
+ * surface show a path as text instead of offering a button that would spawn
+ * `xdg-open` into nothing.
+ * @param internals - platform and environment seam for deterministic tests.
+ * @returns true when handing a path to the native opener can work at all.
+ */
+export function canOpenNativePath(internals = {}) {
+    const platform = internals.platform ?? process.platform;
+    if (platform === 'darwin' || platform === 'win32')
+        return true;
+    if (platform !== 'linux')
+        return false;
+    const env = internals.env ?? process.env;
+    return isWsl(internals) || present(env.DISPLAY) || present(env.WAYLAND_DISPLAY);
+}
+/**
+ * Open a filesystem path with the operating system's default application, or
+ * with the default browser when the path names a document a browser renders.
+ * @param path - absolute or host-resolvable path (caller owns resolution).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - Platform, environment, and runner hooks for deterministic tests.
+ */
+export function openNativePath(path, signal, internals = {}) {
+    return openNativePathWithIntent(path, signal, 'default', internals);
+}
+/**
+ * Open a filesystem path through its file-type association, including HTML and SVG.
+ * @param path - absolute or host-resolvable path; the caller verifies local access.
+ * @param signal - caller lifetime; abort terminates the native command.
+ * @param internals - platform, environment, and runner facts for adapter tests.
+ * @returns after the associated application accepts the path.
+ */
+export function openNativeAssociatedPath(path, signal, internals = {}) {
+    return openNativePathWithIntent(path, signal, 'association', internals);
+}
+/**
+ * Open a text document for editing; macOS bypasses the file-type association
+ * so a YAML association with a browser cannot consume the gesture.
+ * @param path - absolute or host-resolvable text-document path.
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - Platform and runner hooks for deterministic tests.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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');
+        }
+        // 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;
+        }
+        return;
+    }
+    if (manager === 'directory') {
+        await run('xdg-open', [dirname(path)], signal);
+        return;
+    }
+    throw new Error(`native file manager is unsupported on ${platform}`);
+}
+//# sourceMappingURL=path-opener.js.map

package/lib/types/runner.js

@@ -0,0 +1,27 @@
+/**
+ * Shared no-shell `execFile` runner for host-native OS integrations.
+ * @module @deepseek-ai/dsh-native-command/runner
+ */
+import { execFile } from 'node:child_process';
+/**
+ * Run a host command with utf8 stdio, abort propagation, and Windows hide.
+ * @param command - executable path or PATH name.
+ * @param args - argv (never a shell string).
+ * @param signal - caller/connection lifetime; abort terminates the child.
+ * @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) => {
+        if (error !== null) {
+            const failure = Object.assign(new Error(error.message, { cause: error }), {
+                code: error.code,
+                stdout,
+                stderr,
+            });
+            reject(failure);
+            return;
+        }
+        resolve({ stdout, stderr });
+    });
+});
+//# sourceMappingURL=runner.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,18 @@
+/** Browser-safe metadata for native file associations. */
+/** One OS-registered application capable of opening the requested file. */
+export interface NativeFileApplication {
+    /** OS application identifier; callers must revalidate it against the file's current handlers before opening. */
+    readonly id: string;
+    readonly name: string;
+    readonly default: boolean;
+    /** PNG or SVG data URL, or null when the desktop supplies no icon. */
+    readonly icon: string | null;
+}
+/**
+ * Validate file association metadata received from a native process or authenticated Host.
+ * @param value - decoded application list.
+ * @returns validated application metadata.
+ * @throws Error for malformed entries or unsupported icon URLs.
+ */
+export declare function parseNativeFileApplications(value: unknown): readonly NativeFileApplication[];
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,25 @@
+/** Browser-safe metadata for native file associations. */
+/**
+ * Validate file association metadata received from a native process or authenticated Host.
+ * @param value - decoded application list.
+ * @returns validated application metadata.
+ * @throws Error for malformed entries or unsupported icon URLs.
+ */
+export function parseNativeFileApplications(value) {
+    if (!Array.isArray(value))
+        throw new Error('Invalid native application list');
+    const applications = [];
+    const entries = value;
+    for (const entry of entries) {
+        if (typeof entry !== 'object' || entry === null
+            || !('id' in entry) || !('name' in entry) || !('default' in entry) || !('icon' in entry)
+            || typeof entry.id !== 'string' || entry.id.length === 0
+            || typeof entry.name !== 'string' || typeof entry.default !== 'boolean'
+            || !(entry.icon === null || (typeof entry.icon === 'string' && /^data:image\/(?:png|svg\+xml);base64,[A-Za-z0-9+/=]+$/.test(entry.icon)))) {
+            throw new Error('Invalid native application entry');
+        }
+        applications.push({ id: entry.id, name: entry.name, default: entry.default, icon: entry.icon });
+    }
+    return applications;
+}
+//# sourceMappingURL=types.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.6-alpha.2",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -19,17 +19,22 @@
       "default": "./lib/index.js"
     },
     "./src/*": "./src/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    }
   },
   "files": [
     "lib/index.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3"
   }
 }