@x1a0f3n9/dsh-native-command 0.1.5-rc.4 → 0.1.7-rc.2

package/lib/types/file-applications.js

@@ -0,0 +1,191 @@
+/** Native file associations queried from the desktop that owns the path. */
+import { runNativeCommand } from "./runner.js";
+import { linuxFileApplications } from "./file-applications-linux.js";
+import { windowsFileApplications } from "./file-applications-windows.js";
+import { nativeFileManager } from "./path-opener.js";
+import { parseNativeFileApplications } from "./types.js";
+/** AppKit runs inside the system JXA host; paths arrive as argv, never executable source. */
+const MAC_APPLICATIONS = `
+ObjC.import('AppKit');
+function run(argv) {
+  var workspace = $.NSWorkspace.sharedWorkspace;
+  var file = $.NSURL.fileURLWithPath(argv[0]);
+  var preferred = workspace.URLForApplicationToOpenURL(file);
+  var preferredPath = preferred.isNil() ? null : ObjC.unwrap(preferred.path);
+  var urls = workspace.URLsForApplicationsToOpenURL(file);
+  var apps = [];
+  for (var i = 0; i < urls.count; i++) {
+    var url = urls.objectAtIndex(i);
+    var path = ObjC.unwrap(url.path);
+    var image = null;
+    if (argv[1] === 'icons') {
+      var icon = workspace.iconForFile(path);
+      var thumbnail = $.NSImage.alloc.initWithSize($.NSMakeSize(32, 32));
+      thumbnail.lockFocus;
+      icon.drawInRectFromRectOperationFraction($.NSMakeRect(0, 0, 32, 32), $.NSZeroRect, $.NSCompositingOperationSourceOver, 1);
+      thumbnail.unlockFocus;
+      var bitmap = $.NSBitmapImageRep.imageRepWithData(thumbnail.TIFFRepresentation);
+      var png = bitmap.representationUsingTypeProperties($.NSBitmapImageFileTypePNG, $({}));
+      image = png.isNil() ? null : 'data:image/png;base64,' + ObjC.unwrap(png.base64EncodedStringWithOptions(0));
+    }
+    var bundle = $.NSBundle.bundleWithURL(url);
+    var bundleId = bundle.isNil() || bundle.bundleIdentifier.isNil() ? null : ObjC.unwrap(bundle.bundleIdentifier);
+    var version = bundle.isNil() ? null : bundle.objectForInfoDictionaryKey('CFBundleShortVersionString');
+    apps.push({
+      id: path,
+      name: ObjC.unwrap($.NSFileManager.defaultManager.displayNameAtPath(path)),
+      default: path === preferredPath,
+      icon: image,
+      bundle: bundleId,
+      version: version === null || version.isNil() ? null : String(ObjC.unwrap(version))
+    });
+  }
+  return JSON.stringify(apps);
+}`;
+/**
+ * List registered handlers in OS preference order, including the current default and application icons.
+ * @param path - verified absolute local file path.
+ * @param signal - caller lifetime, propagated to the OS query.
+ * @param internals - platform and command adapter for deterministic tests.
+ * @returns current file handlers; on macOS, copies sharing a bundle identifier and display name collapse
+ * to one entry; an empty list when the platform has no association query.
+ */
+export async function nativeFileApplications(path, signal, internals = {}) {
+    return queryFileApplications(path, signal, internals, true);
+}
+/**
+ * Query handler metadata; display queries render macOS icons and collapse duplicate copies,
+ * launch validation keeps every registered copy.
+ */
+async function queryFileApplications(path, signal, internals, display) {
+    signal.throwIfAborted();
+    const target = await desktopTarget(path, signal, internals);
+    const run = internals.run ?? runNativeCommand;
+    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 applications = parseMacApplications(JSON.parse(stdout));
+        return display ? dedupeMacApplications(applications) : applications;
+    }
+    if (target.platform !== 'win32')
+        return [];
+    const stdout = await windowsFileApplications(target.path, null, signal, run);
+    return parseNativeFileApplications(JSON.parse(stdout));
+}
+/**
+ * Validate every entry of the decoded macOS query output, base fields and grouping metadata alike.
+ * @param value - decoded application list from the macOS query.
+ * @returns validated handlers in OS preference order.
+ * @throws Error when any entry is malformed, matching the other platform parsers.
+ */
+function parseMacApplications(value) {
+    if (!Array.isArray(value))
+        throw new Error('Invalid native application list');
+    const entries = value;
+    return entries.map((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            throw new Error('Invalid native application entry');
+        const bundle = macField('bundle' in entry ? entry.bundle : null);
+        const version = macField('version' in entry ? entry.version : null);
+        const [base] = parseNativeFileApplications([entry]);
+        // oxlint-disable-next-line typescript/no-non-null-assertion -- a one-entry input parses to one entry
+        return { ...base, bundle, version };
+    });
+}
+/** Validate one optional string field value of a macOS entry; missing fields, null, and empty strings read as null. */
+function macField(field) {
+    if (field === null)
+        return null;
+    if (typeof field !== 'string')
+        throw new Error('Invalid native application entry');
+    return field.length === 0 ? null : field;
+}
+/**
+ * Collapse duplicate registrations of the same application for display. Self-updating
+ * apps leave extra copies on disk (an update staged under Application Support,
+ * per-version installs) and LaunchServices registers every one, so the raw handler
+ * list repeats the app. Finder shows one entry per app and splits only deliberate
+ * side-by-side installs, which carry distinct display names; matching that, copies
+ * sharing a bundle identifier and display name collapse to the system default, else
+ * the highest version, at the group's first position. Launch validation bypasses
+ * this collapse, so every registered copy stays openable.
+ * @param applications - validated handlers in OS preference order.
+ * @returns application metadata with one entry per application and no grouping metadata.
+ */
+function dedupeMacApplications(applications) {
+    const order = [];
+    const groups = new Map();
+    for (const app of applications) {
+        if (app.bundle === null) {
+            order.push(app);
+            continue;
+        }
+        const key = `${app.bundle}\u0000${app.name}`;
+        const index = groups.get(key);
+        if (index === undefined) {
+            groups.set(key, order.length);
+            order.push(app);
+            continue;
+        }
+        // oxlint-disable-next-line typescript/no-non-null-assertion -- group indices point at pushed entries
+        const held = order[index];
+        if (held.default)
+            continue;
+        if (app.default || compareVersions(app.version, held.version) > 0)
+            order[index] = app;
+    }
+    return order.map(({ id, name, default: preferred, icon }) => ({ id, name, default: preferred, icon }));
+}
+/** Order two dotted version strings numerically; non-numeric segments count as 0, and a missing version sorts lowest. */
+function compareVersions(left, right) {
+    if (left === null || right === null)
+        return left === right ? 0 : left === null ? -1 : 1;
+    const a = left.split('.');
+    const b = right.split('.');
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const difference = (Number(a[i]) || 0) - (Number(b[i]) || 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+/**
+ * Open a file in a currently registered handler; stale or arbitrary application identifiers are rejected.
+ * Validation checks the complete registered list, so macOS copies collapsed out of the display list stay openable.
+ * @param path - verified absolute local file path.
+ * @param application - identifier returned by the file association query.
+ * @param signal - caller lifetime, propagated to query and launch.
+ * @param internals - platform and command adapter for deterministic tests.
+ * @returns after the system launcher accepts the file.
+ */
+export async function openNativeFileApplication(path, application, signal, internals = {}) {
+    const target = await desktopTarget(path, signal, internals);
+    const run = internals.run ?? runNativeCommand;
+    if (target.platform === 'win32') {
+        await windowsFileApplications(target.path, application, signal, run);
+        return;
+    }
+    const apps = await queryFileApplications(path, signal, internals, false);
+    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);
+    else
+        await run('open', ['-a', application, path], signal);
+}
+/** 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);
+        signal.throwIfAborted();
+        const windowsPath = translated.stdout.replace(/[\r\n]+$/, '');
+        if (windowsPath === '')
+            throw new Error('wslpath returned no Windows path');
+        return { platform: 'win32', path: windowsPath };
+    }
+    return { platform, path };
+}
+//# sourceMappingURL=file-applications.js.map

package/lib/types/index.d.ts

@@ -4,6 +4,9 @@
  */
 export { runNativeCommand } from './runner.ts';
 export type { NativeCommandRunner } from './runner.ts';
-export { canOpenNativePath, nativeFileManager, revealNativePath, openNativePath, openNativeTextFile, } from './path-opener.ts';
+export { canOpenNativePath, nativeFileManager, revealNativePath, openNativePath, openNativeAssociatedPath, openNativeTextFile, } from './path-opener.ts';
 export type { NativeFileManager, PathOpenerInternals, PathOpenerRunner, } from './path-opener.ts';
+export { nativeFileApplications, openNativeFileApplication } from './file-applications.ts';
+export type { NativeFileApplication } from './types.ts';
+export { desktopEntryFields, desktopDataDirectories, desktopApplicationIcon } from './desktop-entry.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,9 @@
+/**
+ * Host-native command execution and path-opening utilities.
+ * @module @x1a0f3n9/dsh-native-command
+ */
+export { runNativeCommand } from "./runner.js";
+export { canOpenNativePath, nativeFileManager, revealNativePath, openNativePath, openNativeAssociatedPath, openNativeTextFile, } from "./path-opener.js";
+export { nativeFileApplications, openNativeFileApplication } from "./file-applications.js";
+export { desktopEntryFields, desktopDataDirectories, desktopApplicationIcon } from "./desktop-entry.js";
+//# sourceMappingURL=index.js.map

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 @x1a0f3n9/dsh-native-command/path-opener
  */
 import { type NativeCommandRunner } from './runner.ts';
@@ -40,6 +43,14 @@ export declare function canOpenNativePath(internals?: PathOpenerInternals): bool
  * @param internals - Platform, environment, and runner hooks for deterministic tests.
  */
 export declare function openNativePath(path: string, signal: AbortSignal, internals?: PathOpenerInternals): Promise<void>;
+/**
+ * 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 declare function openNativeAssociatedPath(path: string, signal: AbortSignal, internals?: PathOpenerInternals): Promise<void>;
 /**
  * Open a text document for editing; macOS bypasses the file-type association
  * so a YAML association with a browser cannot consume the gesture.

package/lib/types/path-opener.js

@@ -0,0 +1,267 @@
+/**
+ * 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. 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 @x1a0f3n9/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;
+}
+/** 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');
+}
+/**
+ * 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 runExplorer([explorerTarget(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);
+    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');
+        }
+        await runExplorer(['/select,', explorerTarget(windowsPath)], signal, run);
+        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 @x1a0f3n9/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": "@x1a0f3n9/dsh-native-command",
   "description": "Host-native command and path-opening utilities with shell-free execution, cancellation, desktop detection, and WSL handoff",
-  "version": "0.1.5-rc.4",
+  "version": "0.1.7-rc.2",
   "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.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "~4.0.4"
   }
 }