@flighthq/shell 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './shell';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './shell';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC"}

package/dist/shell.d.ts

@@ -0,0 +1,16 @@
+import type { ShellBackend, ShellOpenExternalOptions, ShellOpenPathOptions, ShellShortcutLink, ShellShortcutWriteOperation } from '@flighthq/types';
+export declare function createWebShellBackend(): ShellBackend;
+export declare function getShellBackend(): ShellBackend;
+export declare function isShellUrlAllowed(url: string): boolean;
+export declare function moveItemsToTrash(paths: readonly string[]): Promise<readonly boolean[]>;
+export declare function moveItemToTrash(path: string): Promise<boolean>;
+export declare function openShellExternalUrl(url: string, options?: Readonly<ShellOpenExternalOptions>): Promise<boolean>;
+export declare function openShellPath(path: string, options?: Readonly<ShellOpenPathOptions>): Promise<boolean>;
+export declare function openShellPathResult(path: string, options?: Readonly<ShellOpenPathOptions>): Promise<string>;
+export declare function readShellShortcutLink(shortcutPath: string): Promise<ShellShortcutLink | null>;
+export declare function setShellBackend(backend: ShellBackend | null): void;
+export declare function setShellUrlSchemeAllowlist(schemes: readonly string[] | null): void;
+export declare function shellBeep(): void;
+export declare function showItemInFolder(path: string): Promise<boolean>;
+export declare function writeShellShortcutLink(shortcutPath: string, link: Readonly<ShellShortcutLink>, operation?: ShellShortcutWriteOperation): Promise<boolean>;
+//# sourceMappingURL=shell.d.ts.map

package/dist/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,EACjB,2BAA2B,EAC5B,MAAM,iBAAiB,CAAC;AAKzB,wBAAgB,qBAAqB,IAAI,YAAY,CA4CpD;AAGD,wBAAgB,eAAe,IAAI,YAAY,CAG9C;AAID,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQtD;AAID,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAEtF;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE9D;AAQD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,wBAAwB,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAGhH;AAGD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAEtG;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAE3G;AAID,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAE7F;AAGD,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAElE;AAMD,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAElF;AAGD,wBAAgB,SAAS,IAAI,IAAI,CAEhC;AAGD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE/D;AAMD,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,QAAQ,CAAC,iBAAiB,CAAC,EACjC,SAAS,CAAC,EAAE,2BAA2B,GACtC,OAAO,CAAC,OAAO,CAAC,CAElB"}

package/dist/shell.js

@@ -0,0 +1,133 @@
+// Builds the default web backend. Only openExternal is achievable on the web (window.open); revealing
+// items, opening arbitrary local paths, trashing, shortcut links, and batch operations require a native
+// host, so they return false / null / error-string sentinels here.
+export function createWebShellBackend() {
+    return {
+        beep() {
+            // No portable web equivalent of a system beep; no-op until a native host provides one.
+        },
+        async moveItemsToTrash() {
+            // The web cannot move local paths to the OS trash; native-host only.
+            return [];
+        },
+        async moveToTrash() {
+            // The web cannot move a local path to the OS trash; native-host only.
+            return false;
+        },
+        async openExternal(url) {
+            // window.open returns a Window handle on success, or null when blocked (popup blocker, no window).
+            // The activate option (macOS foreground raise) has no web equivalent and is silently ignored.
+            if (typeof window === 'undefined' || typeof window.open !== 'function')
+                return false;
+            try {
+                return window.open(url, '_blank', 'noopener') !== null;
+            }
+            catch {
+                return false;
+            }
+        },
+        async openPath() {
+            // The web sandbox cannot open arbitrary local paths; only a native host can.
+            return false;
+        },
+        async openPathResult() {
+            // The web cannot open arbitrary local paths; native-host only.
+            return 'unavailable on web';
+        },
+        async readShortcutLink() {
+            // Windows .lnk shortcut links are not accessible on the web.
+            return null;
+        },
+        async showItemInFolder() {
+            // The web has no OS file manager to reveal an item in; native-host only.
+            return false;
+        },
+        async writeShortcutLink() {
+            // Windows .lnk shortcut links cannot be written on the web.
+            return false;
+        },
+    };
+}
+// The active shell backend, or a lazily-created web default. There is always a backend.
+export function getShellBackend() {
+    if (_backend === null)
+        _backend = createWebShellBackend();
+    return _backend;
+}
+// True when url is allowed by the active URL-scheme allowlist. When no allowlist is set, all URLs
+// are allowed. Used internally by openShellExternalUrl; also exported for callers that need the check.
+export function isShellUrlAllowed(url) {
+    if (_urlSchemeAllowlist === null)
+        return true;
+    try {
+        const scheme = new URL(url).protocol.replace(/:$/, '');
+        return _urlSchemeAllowlist.includes(scheme);
+    }
+    catch {
+        return false;
+    }
+}
+// Moves a batch of local paths to the OS trash. Returns a per-path boolean array. Empty array on the
+// web (native-host only). Single-path convenience: use moveItemToTrash.
+export function moveItemsToTrash(paths) {
+    return getShellBackend().moveItemsToTrash(paths);
+}
+// Moves a local path to the OS trash. Returns false on the web; native-host capability.
+export function moveItemToTrash(path) {
+    return getShellBackend().moveToTrash(path);
+}
+// Opens a URL in the user's default browser / external handler. Returns false when blocked, popup-
+// blocked, or the URL scheme is not in the active allowlist (see setShellUrlSchemeAllowlist).
+// SECURITY: handing an attacker-controlled URL to the OS default handler is the classic openExternal
+// footgun — a non-http(s) scheme can launch a local application or protocol handler. When the url may
+// be untrusted, constrain the accepted schemes with setShellUrlSchemeAllowlist (e.g. ['https',
+// 'mailto']); isShellUrlAllowed exposes the same check for a caller that wants to gate the URL itself.
+export function openShellExternalUrl(url, options) {
+    if (!isShellUrlAllowed(url))
+        return Promise.resolve(false);
+    return getShellBackend().openExternal(url, options);
+}
+// Opens a local path with its default OS application. Returns false on the web; native-host capability.
+export function openShellPath(path, options) {
+    return getShellBackend().openPath(path, options);
+}
+// Opens a local path and returns the OS error message, or '' on success. On the web returns
+// 'unavailable on web'. Use this when you need the reason a path could not be opened rather than
+// just a boolean; openShellPath is the boolean convenience wrapper over this.
+export function openShellPathResult(path, options) {
+    return getShellBackend().openPathResult(path, options);
+}
+// Reads a Windows .lnk shell shortcut. Returns null on non-Windows platforms, on the web, or when
+// the shortcut does not exist.
+export function readShellShortcutLink(shortcutPath) {
+    return getShellBackend().readShortcutLink(shortcutPath);
+}
+// Installs a native host shell backend; pass null to fall back to the web default.
+export function setShellBackend(backend) {
+    _backend = backend;
+}
+// Sets the URL-scheme allowlist consulted by openShellExternalUrl. Pass null to allow all schemes
+// (default behavior). When a non-null list is set, openShellExternalUrl returns false for any URL whose
+// scheme is not in the list. Example: setShellUrlSchemeAllowlist(['https', 'mailto']).
+// This closes the classic openExternal security footgun with attacker-controlled URLs.
+export function setShellUrlSchemeAllowlist(schemes) {
+    _urlSchemeAllowlist = schemes;
+}
+// Emits a system beep. No-op on the web until a native host provides one.
+export function shellBeep() {
+    getShellBackend().beep();
+}
+// Reveals a local path in the OS file manager. Returns false on the web; native-host capability.
+export function showItemInFolder(path) {
+    return getShellBackend().showItemInFolder(path);
+}
+// Creates a Windows .lnk shell shortcut at shortcutPath pointing to link. Returns false on
+// non-Windows platforms and on the web. operation defaults to 'create'.
+// IMPORTANT: URL safety — only use openShellExternalUrl for user-facing link opening; do not pass
+// attacker-controlled paths to writeShellShortcutLink without validation.
+export function writeShellShortcutLink(shortcutPath, link, operation) {
+    return getShellBackend().writeShortcutLink(shortcutPath, link, operation);
+}
+let _backend = null;
+let _urlSchemeAllowlist = null;
+//# sourceMappingURL=shell.js.map

package/dist/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flighthq/shell",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "OS shell integration over a swappable web/native backend: open external URLs and paths, reveal items in the file manager, move to trash, beep",
+  "sideEffects": false
+}

package/src/shell.test.ts

@@ -0,0 +1,313 @@
+import type { ShellBackend, ShellOpenExternalOptions, ShellOpenPathOptions } from '@flighthq/types';
+
+import {
+  createWebShellBackend,
+  getShellBackend,
+  isShellUrlAllowed,
+  moveItemsToTrash,
+  moveItemToTrash,
+  openShellExternalUrl,
+  openShellPath,
+  openShellPathResult,
+  readShellShortcutLink,
+  setShellBackend,
+  setShellUrlSchemeAllowlist,
+  shellBeep,
+  showItemInFolder,
+  writeShellShortcutLink,
+} from './shell';
+
+function fakeBackend(): ShellBackend & {
+  beeped: number;
+  lastOptions: ShellOpenExternalOptions | ShellOpenPathOptions | undefined;
+  opened: string;
+  pathResult: string;
+  trashed: string;
+  trashedBatch: readonly string[];
+} {
+  return {
+    beeped: 0,
+    lastOptions: undefined,
+    opened: '',
+    pathResult: '',
+    trashed: '',
+    trashedBatch: [],
+    beep() {
+      this.beeped += 1;
+    },
+    async moveItemsToTrash(paths) {
+      this.trashedBatch = paths;
+      return paths.map(() => true);
+    },
+    async moveToTrash(path) {
+      this.trashed = path;
+      return true;
+    },
+    async openExternal(url, options) {
+      this.opened = url;
+      this.lastOptions = options;
+      return true;
+    },
+    async openPath(path, options) {
+      this.opened = path;
+      this.lastOptions = options;
+      return true;
+    },
+    async openPathResult(path, options) {
+      this.opened = path;
+      this.lastOptions = options;
+      return this.pathResult;
+    },
+    async readShortcutLink() {
+      return { target: '/path/to/target' };
+    },
+    async showItemInFolder(path) {
+      this.opened = path;
+      return true;
+    },
+    async writeShortcutLink() {
+      return true;
+    },
+  };
+}
+
+afterEach(() => {
+  setShellBackend(null);
+  setShellUrlSchemeAllowlist(null);
+});
+
+describe('createWebShellBackend', () => {
+  it('returns a backend whose native-only operations resolve to sentinels without throwing', async () => {
+    const backend = createWebShellBackend();
+    expect(await backend.openPath('/tmp/x')).toBe(false);
+    expect(await backend.showItemInFolder('/tmp/x')).toBe(false);
+    expect(await backend.moveToTrash('/tmp/x')).toBe(false);
+    expect(await backend.writeShortcutLink('/tmp/x.lnk', { target: '/tmp/x' })).toBe(false);
+    expect(await backend.readShortcutLink('/tmp/x.lnk')).toBeNull();
+    expect(() => backend.beep()).not.toThrow();
+  });
+
+  it('batch trash resolves to an empty array on the web', async () => {
+    const backend = createWebShellBackend();
+    expect(await backend.moveItemsToTrash(['/tmp/a', '/tmp/b'])).toEqual([]);
+  });
+
+  it('openPathResult returns the unavailable-on-web sentinel string', async () => {
+    const backend = createWebShellBackend();
+    expect(await backend.openPathResult('/tmp/x')).toBe('unavailable on web');
+  });
+
+  it('openExternal type-checks to boolean regardless of options', async () => {
+    const backend = createWebShellBackend();
+    expect(typeof (await backend.openExternal('https://example.com'))).toBe('boolean');
+    expect(typeof (await backend.openExternal('https://example.com', { activate: true }))).toBe('boolean');
+  });
+});
+
+describe('getShellBackend', () => {
+  it('falls back to a web backend', () => {
+    expect(getShellBackend()).not.toBeNull();
+  });
+
+  it('returns the registered backend', () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    expect(getShellBackend()).toBe(backend);
+  });
+});
+
+describe('isShellUrlAllowed', () => {
+  it('returns true when no allowlist is set', () => {
+    expect(isShellUrlAllowed('https://example.com')).toBe(true);
+    expect(isShellUrlAllowed('file:///tmp/x')).toBe(true);
+  });
+
+  it('returns true for a scheme in the allowlist', () => {
+    setShellUrlSchemeAllowlist(['https', 'mailto']);
+    expect(isShellUrlAllowed('https://example.com')).toBe(true);
+    expect(isShellUrlAllowed('mailto:user@example.com')).toBe(true);
+  });
+
+  it('returns false for a scheme not in the allowlist', () => {
+    setShellUrlSchemeAllowlist(['https']);
+    expect(isShellUrlAllowed('file:///tmp/x')).toBe(false);
+    expect(isShellUrlAllowed('ftp://example.com')).toBe(false);
+  });
+
+  it('returns false for a URL that cannot be parsed', () => {
+    setShellUrlSchemeAllowlist(['https']);
+    expect(isShellUrlAllowed('not-a-url')).toBe(false);
+  });
+});
+
+describe('moveItemsToTrash', () => {
+  it('passes the path array to the backend and returns per-path results', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    const results = await moveItemsToTrash(['/tmp/a', '/tmp/b']);
+    expect(results).toEqual([true, true]);
+    expect(backend.trashedBatch).toEqual(['/tmp/a', '/tmp/b']);
+  });
+});
+
+describe('moveItemToTrash', () => {
+  it('trashes via the active backend', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    expect(await moveItemToTrash('/tmp/x')).toBe(true);
+    expect(backend.trashed).toBe('/tmp/x');
+  });
+});
+
+describe('openShellExternalUrl', () => {
+  it('opens via the active backend', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    expect(await openShellExternalUrl('https://example.com')).toBe(true);
+    expect(backend.opened).toBe('https://example.com');
+  });
+
+  it('forwards the activate option to the backend', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    await openShellExternalUrl('https://example.com', { activate: true });
+    expect(backend.lastOptions).toEqual({ activate: true });
+  });
+
+  it('returns false and does not call the backend when the URL scheme is blocked', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    setShellUrlSchemeAllowlist(['https']);
+    expect(await openShellExternalUrl('file:///etc/passwd')).toBe(false);
+    expect(backend.opened).toBe('');
+  });
+
+  it('allows the URL when its scheme is in the allowlist', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    setShellUrlSchemeAllowlist(['https', 'mailto']);
+    expect(await openShellExternalUrl('https://example.com')).toBe(true);
+    expect(backend.opened).toBe('https://example.com');
+  });
+});
+
+describe('openShellPath', () => {
+  it('opens via the active backend', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    expect(await openShellPath('/tmp/x')).toBe(true);
+    expect(backend.opened).toBe('/tmp/x');
+  });
+
+  it('forwards the workingDirectory option to the backend', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    await openShellPath('/tmp/x', { workingDirectory: '/home/user' });
+    expect(backend.lastOptions).toEqual({ workingDirectory: '/home/user' });
+  });
+
+  it('forwards the application option to the backend', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    await openShellPath('/tmp/x', { application: 'TextEdit' });
+    expect(backend.lastOptions).toEqual({ application: 'TextEdit' });
+  });
+
+  it('omits options when none provided', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    await openShellPath('/tmp/x');
+    expect(backend.lastOptions).toBeUndefined();
+  });
+});
+
+describe('openShellPathResult', () => {
+  it('returns an empty string on success', async () => {
+    const backend = fakeBackend();
+    backend.pathResult = '';
+    setShellBackend(backend);
+    expect(await openShellPathResult('/tmp/x')).toBe('');
+    expect(backend.opened).toBe('/tmp/x');
+  });
+
+  it('returns the OS error string on failure', async () => {
+    const backend = fakeBackend();
+    backend.pathResult = 'No such file or directory';
+    setShellBackend(backend);
+    expect(await openShellPathResult('/nonexistent')).toBe('No such file or directory');
+  });
+
+  it('forwards options to the backend', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    await openShellPathResult('/tmp/x', { workingDirectory: '/home/user' });
+    expect(backend.lastOptions).toEqual({ workingDirectory: '/home/user' });
+  });
+});
+
+describe('readShellShortcutLink', () => {
+  it('returns null on the web (no backend set)', async () => {
+    const result = await readShellShortcutLink('/tmp/x.lnk');
+    expect(result).toBeNull();
+  });
+
+  it('returns the shortcut link from the active backend', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    const result = await readShellShortcutLink('/tmp/x.lnk');
+    expect(result).toEqual({ target: '/path/to/target' });
+  });
+});
+
+describe('setShellBackend', () => {
+  it('clears back to the web fallback when passed null', () => {
+    setShellBackend(fakeBackend());
+    setShellBackend(null);
+    expect(getShellBackend()).not.toBeNull();
+  });
+});
+
+describe('setShellUrlSchemeAllowlist', () => {
+  it('allows all URLs when set to null', () => {
+    setShellUrlSchemeAllowlist(['https']);
+    setShellUrlSchemeAllowlist(null);
+    expect(isShellUrlAllowed('file:///tmp/x')).toBe(true);
+  });
+
+  it('restricts URLs to the listed schemes', () => {
+    setShellUrlSchemeAllowlist(['https', 'mailto']);
+    expect(isShellUrlAllowed('ftp://example.com')).toBe(false);
+  });
+});
+
+describe('shellBeep', () => {
+  it('forwards to the active backend', () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    shellBeep();
+    expect(backend.beeped).toBe(1);
+  });
+});
+
+describe('showItemInFolder', () => {
+  it('reveals via the active backend', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    expect(await showItemInFolder('/tmp/x')).toBe(true);
+    expect(backend.opened).toBe('/tmp/x');
+  });
+});
+
+describe('writeShellShortcutLink', () => {
+  it('returns false on the web (no backend set)', async () => {
+    const result = await writeShellShortcutLink('/tmp/x.lnk', { target: '/tmp/target' });
+    expect(result).toBe(false);
+  });
+
+  it('writes via the active backend', async () => {
+    const backend = fakeBackend();
+    setShellBackend(backend);
+    const result = await writeShellShortcutLink('/tmp/x.lnk', { target: '/tmp/target' }, 'create');
+    expect(result).toBe(true);
+  });
+});