@flighthq/shell 0.4.0-next.1898.266773a → 0.4.0-next.1908.751021c

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { isShellUrlAllowed, moveItemToTrash, moveItemsToTrash, openShellExternalUrl, openShellPath, openShellPathResult, readShellShortcutLink, setShellUrlSchemeAllowlist, shellBeep, showItemInFolder, writeShellShortcutLink, } from './contract';
+export { explainShellBackend, isShellUrlAllowed, moveItemToTrash, moveItemsToTrash, openShellExternalUrl, openShellPath, openShellPathResult, readShellShortcutLink, setShellUrlSchemeAllowlist, shellBeep, showItemInFolder, writeShellShortcutLink, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,EAC1B,SAAS,EACT,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,EAC1B,SAAS,EACT,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { isShellUrlAllowed, moveItemToTrash, moveItemsToTrash, openShellExternalUrl, openShellPath, openShellPathResult, readShellShortcutLink, setShellUrlSchemeAllowlist, shellBeep, showItemInFolder, writeShellShortcutLink, } from './contract';
+export { explainShellBackend, isShellUrlAllowed, moveItemToTrash, moveItemsToTrash, openShellExternalUrl, openShellPath, openShellPathResult, readShellShortcutLink, setShellUrlSchemeAllowlist, shellBeep, showItemInFolder, writeShellShortcutLink, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,EAC1B,SAAS,EACT,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,EAC1B,SAAS,EACT,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/shell.d.ts

@@ -1,13 +1,17 @@
+import type { BackendExplanation } from '@flighthq/types/contract';
 import type { ShellBackend, ShellOpenExternalOptions, ShellOpenPathOptions, ShellShortcutLink, ShellShortcutWriteOperation } from '@flighthq/types/contract';
-export declare function createWebShellBackend(): ShellBackend;
+export declare function explainShellBackend(): BackendExplanation;
 export declare function getShellBackend(): ShellBackend;
+export declare function installShellHostBackend(backend: ShellBackend): void;
 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 observeShellHostResult(operation: string, succeeded: boolean): void;
 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 resetShellBackendForTest(): void;
 export declare function setShellBackend(backend: ShellBackend | null): void;
 export declare function setShellUrlSchemeAllowlist(schemes: readonly string[] | null): void;
 export declare function shellBeep(): void;

package/dist/shell.d.ts.map

@@ -1 +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,0BAA0B,CAAC;AAKlC,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"}
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,EACjB,2BAA2B,EAC5B,MAAM,0BAA0B,CAAC;AAElC,wBAAgB,mBAAmB,IAAI,kBAAkB,CAaxD;AAGD,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAMnE;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;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAKlF;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;AAED,wBAAgB,wBAAwB,IAAI,IAAI,CAK/C;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

@@ -1,58 +1,28 @@
-// 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;
-        },
-    };
+export function explainShellBackend() {
+    if (_custom !== null) {
+        return { conflict: _hostConflict, layer: 'custom', operation: null, viability: 'unobserved' };
+    }
+    if (_host !== null) {
+        return {
+            conflict: _hostConflict,
+            layer: 'host',
+            operation: _hostObservation !== null ? _hostObservation.operation : null,
+            viability: _hostObservation !== null ? _hostObservation.viability : 'unobserved',
+        };
+    }
+    return { conflict: false, layer: 'host-not-enabled', operation: null, viability: 'unobserved' };
 }
-// The active shell backend, or a lazily-created web default. There is always a backend.
+// The active shell backend. Precedence: custom > host > sentinel.
 export function getShellBackend() {
-    if (_backend === null)
-        _backend = createWebShellBackend();
-    return _backend;
+    return _custom ?? _host ?? _sentinel;
+}
+export function installShellHostBackend(backend) {
+    if (_host !== null) {
+        if (_host !== backend)
+            _hostConflict = true;
+        return;
+    }
+    _host = 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.
@@ -76,6 +46,12 @@ export function moveItemsToTrash(paths) {
 export function moveItemToTrash(path) {
     return getShellBackend().moveToTrash(path);
 }
+export function observeShellHostResult(operation, succeeded) {
+    _hostObservation = {
+        operation,
+        viability: succeeded ? 'available' : 'runtime-api-unavailable',
+    };
+}
 // 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
@@ -102,9 +78,15 @@ export function openShellPathResult(path, options) {
 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 resetShellBackendForTest() {
+    _custom = null;
+    _host = null;
+    _hostConflict = false;
+    _hostObservation = null;
+}
+// Installs a custom shell backend; pass null to clear the custom override.
 export function setShellBackend(backend) {
-    _backend = backend;
+    _custom = 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
@@ -128,6 +110,36 @@ export function showItemInFolder(path) {
 export function writeShellShortcutLink(shortcutPath, link, operation) {
     return getShellBackend().writeShortcutLink(shortcutPath, link, operation);
 }
-let _backend = null;
+const _sentinel = {
+    beep() { },
+    async moveItemsToTrash() {
+        return [];
+    },
+    async moveToTrash() {
+        return false;
+    },
+    async openExternal() {
+        return false;
+    },
+    async openPath() {
+        return false;
+    },
+    async openPathResult() {
+        return 'unavailable on web';
+    },
+    async readShortcutLink() {
+        return null;
+    },
+    async showItemInFolder() {
+        return false;
+    },
+    async writeShortcutLink() {
+        return false;
+    },
+};
+let _custom = null;
+let _host = null;
+let _hostConflict = false;
+let _hostObservation = null;
 let _urlSchemeAllowlist = null;
 //# sourceMappingURL=shell.js.map

package/dist/shell.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/shell",
-  "version": "0.4.0-next.1898.266773a",
+  "version": "0.4.0-next.1908.751021c",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.4.0-next.1898.266773a"
+    "@flighthq/types": "0.4.0-next.1908.751021c"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/shell.test.ts

@@ -1,15 +1,18 @@
 import type { ShellBackend, ShellOpenExternalOptions, ShellOpenPathOptions } from '@flighthq/types/contract';
 
 import {
-  createWebShellBackend,
+  explainShellBackend,
   getShellBackend,
+  installShellHostBackend,
   isShellUrlAllowed,
   moveItemsToTrash,
   moveItemToTrash,
+  observeShellHostResult,
   openShellExternalUrl,
   openShellPath,
   openShellPathResult,
   readShellShortcutLink,
+  resetShellBackendForTest,
   setShellBackend,
   setShellUrlSchemeAllowlist,
   shellBeep,
@@ -72,40 +75,33 @@ function fakeBackend(): ShellBackend & {
 }
 
 afterEach(() => {
-  setShellBackend(null);
+  resetShellBackendForTest();
   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();
+describe('explainShellBackend', () => {
+  it('returns host-not-enabled when no backend is installed', () => {
+    expect(explainShellBackend()).toEqual({
+      conflict: false,
+      layer: 'host-not-enabled',
+      operation: null,
+      viability: 'unobserved',
+    });
   });
 
-  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('returns custom layer when a custom backend is set', () => {
+    setShellBackend(fakeBackend());
+    expect(explainShellBackend().layer).toBe('custom');
   });
 
-  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');
+  it('returns host layer when a host backend is installed', () => {
+    installShellHostBackend(fakeBackend());
+    expect(explainShellBackend().layer).toBe('host');
   });
 });
 
 describe('getShellBackend', () => {
-  it('falls back to a web backend', () => {
+  it('falls back to sentinel', () => {
     expect(getShellBackend()).not.toBeNull();
   });
 
@@ -116,6 +112,23 @@ describe('getShellBackend', () => {
   });
 });
 
+describe('installShellHostBackend', () => {
+  it('first-host-wins and sets conflict on second different backend', () => {
+    const first = fakeBackend();
+    const second = fakeBackend();
+    installShellHostBackend(first);
+    installShellHostBackend(second);
+    expect(explainShellBackend().conflict).toBe(true);
+  });
+
+  it('does not set conflict when the same backend is installed twice', () => {
+    const backend = fakeBackend();
+    installShellHostBackend(backend);
+    installShellHostBackend(backend);
+    expect(explainShellBackend().conflict).toBe(false);
+  });
+});
+
 describe('isShellUrlAllowed', () => {
   it('returns true when no allowlist is set', () => {
     expect(isShellUrlAllowed('https://example.com')).toBe(true);
@@ -159,6 +172,24 @@ describe('moveItemToTrash', () => {
   });
 });
 
+describe('observeShellHostResult', () => {
+  it('records a successful observation into the explanation', () => {
+    installShellHostBackend(fakeBackend());
+    observeShellHostResult('openExternal', true);
+    const explanation = explainShellBackend();
+    expect(explanation.operation).toBe('openExternal');
+    expect(explanation.viability).toBe('available');
+  });
+
+  it('records a failed observation into the explanation', () => {
+    installShellHostBackend(fakeBackend());
+    observeShellHostResult('openExternal', false);
+    const explanation = explainShellBackend();
+    expect(explanation.operation).toBe('openExternal');
+    expect(explanation.viability).toBe('runtime-api-unavailable');
+  });
+});
+
 describe('openShellExternalUrl', () => {
   it('opens via the active backend', async () => {
     const backend = fakeBackend();
@@ -246,7 +277,7 @@ describe('openShellPathResult', () => {
 });
 
 describe('readShellShortcutLink', () => {
-  it('returns null on the web (no backend set)', async () => {
+  it('returns null with sentinel (no backend set)', async () => {
     const result = await readShellShortcutLink('/tmp/x.lnk');
     expect(result).toBeNull();
   });
@@ -259,8 +290,17 @@ describe('readShellShortcutLink', () => {
   });
 });
 
+describe('resetShellBackendForTest', () => {
+  it('clears all backend slots', () => {
+    setShellBackend(fakeBackend());
+    installShellHostBackend(fakeBackend());
+    resetShellBackendForTest();
+    expect(explainShellBackend().layer).toBe('host-not-enabled');
+  });
+});
+
 describe('setShellBackend', () => {
-  it('clears back to the web fallback when passed null', () => {
+  it('clears back to sentinel when passed null', () => {
     setShellBackend(fakeBackend());
     setShellBackend(null);
     expect(getShellBackend()).not.toBeNull();
@@ -299,7 +339,7 @@ describe('showItemInFolder', () => {
 });
 
 describe('writeShellShortcutLink', () => {
-  it('returns false on the web (no backend set)', async () => {
+  it('returns false with sentinel (no backend set)', async () => {
     const result = await writeShellShortcutLink('/tmp/x.lnk', { target: '/tmp/target' });
     expect(result).toBe(false);
   });