@flighthq/shell 0.5.0-next.1944.cd6b6e7 → 0.5.1-edge.1047.858b9b6

package/README.md

@@ -1,6 +1,6 @@
 # @flighthq/shell
 
-OS shell integration over a swappable web/native backend: open external URLs and paths, reveal items in the file manager, move to trash, beep
+OS shell commands over seven explicit Host capability slots with required external URL policy
 
 ## Install
 
@@ -13,5 +13,5 @@ Import the supported application-facing API from `@flighthq/shell`. The `@flight
 This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
 
 - [Flight project](https://github.com/flighthq/flight)
-- [Source for @flighthq/shell@0.5.0-next.1944.cd6b6e7](https://github.com/flighthq/flight/tree/cd6b6e71eb472b3a4249830a7743333f019fa7b7/packages/shell)
-- [License](https://github.com/flighthq/flight/blob/cd6b6e71eb472b3a4249830a7743333f019fa7b7/LICENSE.md)
+- [Source for @flighthq/shell@0.5.1-edge.1047.858b9b6](https://github.com/flighthq/flight/tree/858b9b601de814f6b6940cbb1ffff0916b903268/packages/shell)
+- [License](https://github.com/flighthq/flight/blob/858b9b601de814f6b6940cbb1ffff0916b903268/LICENSE.md)

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { explainShellBackend, isShellUrlAllowed, moveItemToTrash, moveItemsToTrash, openShellExternalUrl, openShellPath, openShellPathResult, readShellShortcutLink, setShellUrlSchemeAllowlist, shellBeep, showItemInFolder, writeShellShortcutLink, } from './contract';
+export { isShellUrlAllowed, moveShellItemToTrash, moveShellItemsToTrash, openShellExternalUrl, openShellPath, readShellShortcutLink, revealShellPath, shellBeep, spawnShellProcess, 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,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { explainShellBackend, isShellUrlAllowed, moveItemToTrash, moveItemsToTrash, openShellExternalUrl, openShellPath, openShellPathResult, readShellShortcutLink, setShellUrlSchemeAllowlist, shellBeep, showItemInFolder, writeShellShortcutLink, } from './contract';
+export { isShellUrlAllowed, moveShellItemToTrash, moveShellItemsToTrash, openShellExternalUrl, openShellPath, readShellShortcutLink, revealShellPath, shellBeep, spawnShellProcess, 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,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/shell.d.ts

@@ -1,20 +1,12 @@
-import type { BackendExplanation } from '@flighthq/types/contract';
-import type { ShellBackend, ShellOpenExternalOptions, ShellOpenPathOptions, ShellShortcutLink, ShellShortcutWriteOperation } from '@flighthq/types/contract';
-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;
-export declare function showItemInFolder(path: string): Promise<boolean>;
-export declare function writeShellShortcutLink(shortcutPath: string, link: Readonly<ShellShortcutLink>, operation?: ShellShortcutWriteOperation): Promise<boolean>;
+import type { HasShellBeep, HasShellExternal, HasShellPathOpen, HasShellPathReveal, HasShellShortcutLink, HasShellTrash, ShellExternalOutcome, ShellExternalUrlPolicy, ShellPathOpenOutcome, ShellPathRevealOutcome, ShellProcess, ShellProcessHost, ShellProcessOptions, ShellShortcutLink, ShellShortcutLinkReadOutcome, ShellShortcutLinkWriteOutcome, ShellShortcutWriteOperation, ShellTrashOutcome } from '@flighthq/types/contract';
+export declare function isShellUrlAllowed(url: string, policy: Readonly<ShellExternalUrlPolicy>): boolean;
+export declare function moveShellItemsToTrash(host: HasShellTrash, paths: readonly string[]): Promise<readonly ShellTrashOutcome[]>;
+export declare function moveShellItemToTrash(host: HasShellTrash, path: string): Promise<ShellTrashOutcome>;
+export declare function openShellExternalUrl(host: HasShellExternal, url: string, policy: Readonly<ShellExternalUrlPolicy>): Promise<ShellExternalOutcome>;
+export declare function openShellPath(host: HasShellPathOpen, path: string): Promise<ShellPathOpenOutcome>;
+export declare function readShellShortcutLink(host: HasShellShortcutLink, shortcutPath: string): Promise<ShellShortcutLinkReadOutcome>;
+export declare function revealShellPath(host: HasShellPathReveal, path: string): Promise<ShellPathRevealOutcome>;
+export declare function shellBeep(host: HasShellBeep): void;
+export declare function spawnShellProcess(host: ShellProcessHost, command: string, args: readonly string[], options?: Readonly<ShellProcessOptions>): ShellProcess | null;
+export declare function writeShellShortcutLink(host: HasShellShortcutLink, shortcutPath: string, link: Readonly<ShellShortcutLink>, operation: ShellShortcutWriteOperation): Promise<ShellShortcutLinkWriteOutcome>;
 //# sourceMappingURL=shell.d.ts.map

package/dist/shell.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,4BAA4B,EAC5B,6BAA6B,EAC7B,2BAA2B,EAC3B,iBAAiB,EAClB,MAAM,0BAA0B,CAAC;AAIlC,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GAAG,OAAO,CAOhG;AAID,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAEvC;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAElG;AAKD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GACvC,OAAO,CAAC,oBAAoB,CAAC,CAG/B;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAEjG;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,oBAAoB,EAC1B,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,4BAA4B,CAAC,CAEvC;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAEvG;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAElD;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,CAAC,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GACtC,YAAY,GAAG,IAAI,CAErB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,oBAAoB,EAC1B,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,QAAQ,CAAC,iBAAiB,CAAC,EACjC,SAAS,EAAE,2BAA2B,GACrC,OAAO,CAAC,6BAA6B,CAAC,CAExC"}

package/dist/shell.js

@@ -1,145 +1,46 @@
-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. Precedence: custom > host > sentinel.
-export function getShellBackend() {
-    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.
-export function isShellUrlAllowed(url) {
-    if (_urlSchemeAllowlist === null)
-        return true;
+// Pure policy validation used by openShellExternalUrl before any host effect. Callers must supply the
+// policy on every invocation; an empty allowedSchemes array intentionally blocks every URL.
+export function isShellUrlAllowed(url, policy) {
     try {
-        const scheme = new URL(url).protocol.replace(/:$/, '');
-        return _urlSchemeAllowlist.includes(scheme);
+        const scheme = new URL(url).protocol.replace(/:$/, '').toLowerCase();
+        return policy.allowedSchemes.some((allowed) => allowed.toLowerCase() === 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);
-}
-export function observeShellHostResult(operation, succeeded) {
-    _hostObservation = {
-        operation,
-        viability: succeeded ? 'available' : 'runtime-api-unavailable',
-    };
+// Projects the one-path provider operation across the batch. Promise.all starts every operation,
+// awaits every settlement, and returns outcomes in the same order as paths.
+export function moveShellItemsToTrash(host, paths) {
+    return Promise.all(paths.map((path) => host.shell.trash.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);
+export function moveShellItemToTrash(host, path) {
+    return host.shell.trash.moveToTrash(path);
 }
-// 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);
+// Handing a URL to an OS handler can launch a local application or registered protocol. The required
+// per-call policy is validated before dispatch, so a blocked or malformed scheme never reaches the
+// host. There is intentionally no policy default, ambient allowlist, or allow-all path.
+export function openShellExternalUrl(host, url, policy) {
+    if (!isShellUrlAllowed(url, policy))
+        return Promise.resolve({ reason: 'blocked-scheme' });
+    return host.shell.external.open(url);
 }
-// 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);
+export function openShellPath(host, path) {
+    return host.shell.pathOpen.open(path);
 }
-// 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);
+export function readShellShortcutLink(host, shortcutPath) {
+    return host.shell.shortcutLink.read(shortcutPath);
 }
-export function resetShellBackendForTest() {
-    _custom = null;
-    _host = null;
-    _hostConflict = false;
-    _hostObservation = null;
+export function revealShellPath(host, path) {
+    return host.shell.pathReveal.reveal(path);
 }
-// Installs a custom shell backend; pass null to clear the custom override.
-export function setShellBackend(backend) {
-    _custom = backend;
+export function shellBeep(host) {
+    host.shell.beep.beep();
 }
-// 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;
+export function spawnShellProcess(host, command, args, options) {
+    return host.shell.process?.spawn(command, args, options) ?? null;
 }
-// Emits a system beep. No-op on the web until a native host provides one.
-export function shellBeep() {
-    getShellBackend().beep();
+export function writeShellShortcutLink(host, shortcutPath, link, operation) {
+    return host.shell.shortcutLink.write(shortcutPath, link, operation);
 }
-// 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);
-}
-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":"AASA,MAAM,UAAU,mBAAmB;IACjC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;IAChG,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO;YACL,QAAQ,EAAE,aAAa;YACvB,KAAK,EAAE,MAAM;YACb,SAAS,EAAE,gBAAgB,KAAK,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;YACxE,SAAS,EAAE,gBAAgB,KAAK,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY;SACjF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AAClG,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,eAAe;IAC7B,OAAO,OAAO,IAAI,KAAK,IAAI,SAAS,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,OAAqB;IAC3D,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,IAAI,KAAK,KAAK,OAAO;YAAE,aAAa,GAAG,IAAI,CAAC;QAC5C,OAAO;IACT,CAAC;IACD,KAAK,GAAG,OAAO,CAAC;AAClB,CAAC;AAED,kGAAkG;AAClG,uGAAuG;AACvG,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,mBAAmB,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvD,OAAO,mBAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,qGAAqG;AACrG,wEAAwE;AACxE,MAAM,UAAU,gBAAgB,CAAC,KAAwB;IACvD,OAAO,eAAe,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;AACnD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,eAAe,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,SAAiB,EAAE,SAAkB;IAC1E,gBAAgB,GAAG;QACjB,SAAS;QACT,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,yBAAyB;KAC/D,CAAC;AACJ,CAAC;AAED,mGAAmG;AACnG,8FAA8F;AAC9F,qGAAqG;AACrG,sGAAsG;AACtG,+FAA+F;AAC/F,uGAAuG;AACvG,MAAM,UAAU,oBAAoB,CAAC,GAAW,EAAE,OAA4C;IAC5F,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3D,OAAO,eAAe,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,OAAwC;IAClF,OAAO,eAAe,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED,4FAA4F;AAC5F,iGAAiG;AACjG,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,OAAwC;IACxF,OAAO,eAAe,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC;AAED,kGAAkG;AAClG,+BAA+B;AAC/B,MAAM,UAAU,qBAAqB,CAAC,YAAoB;IACxD,OAAO,eAAe,EAAE,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,wBAAwB;IACtC,OAAO,GAAG,IAAI,CAAC;IACf,KAAK,GAAG,IAAI,CAAC;IACb,aAAa,GAAG,KAAK,CAAC;IACtB,gBAAgB,GAAG,IAAI,CAAC;AAC1B,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,eAAe,CAAC,OAA4B;IAC1D,OAAO,GAAG,OAAO,CAAC;AACpB,CAAC;AAED,kGAAkG;AAClG,wGAAwG;AACxG,uFAAuF;AACvF,uFAAuF;AACvF,MAAM,UAAU,0BAA0B,CAAC,OAAiC;IAC1E,mBAAmB,GAAG,OAAO,CAAC;AAChC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,SAAS;IACvB,eAAe,EAAE,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,eAAe,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,2FAA2F;AAC3F,wEAAwE;AACxE,kGAAkG;AAClG,0EAA0E;AAC1E,MAAM,UAAU,sBAAsB,CACpC,YAAoB,EACpB,IAAiC,EACjC,SAAuC;IAEvC,OAAO,eAAe,EAAE,CAAC,iBAAiB,CAAC,YAAY,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,SAAS,GAAiB;IAC9B,IAAI,KAAI,CAAC;IACT,KAAK,CAAC,gBAAgB;QACpB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,KAAK,CAAC,WAAW;QACf,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,CAAC,YAAY;QAChB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,CAAC,QAAQ;QACZ,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,CAAC,cAAc;QAClB,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IACD,KAAK,CAAC,gBAAgB;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,CAAC,gBAAgB;QACpB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,CAAC,iBAAiB;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;CACF,CAAC;AACF,IAAI,OAAO,GAAwB,IAAI,CAAC;AACxC,IAAI,KAAK,GAAwB,IAAI,CAAC;AACtC,IAAI,aAAa,GAAG,KAAK,CAAC;AAC1B,IAAI,gBAAgB,GAAqF,IAAI,CAAC;AAC9G,IAAI,mBAAmB,GAA6B,IAAI,CAAC"}
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAqBA,sGAAsG;AACtG,4FAA4F;AAC5F,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,MAAwC;IACrF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACrE,OAAO,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC;IACnF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,4EAA4E;AAC5E,MAAM,UAAU,qBAAqB,CACnC,IAAmB,EACnB,KAAwB;IAExB,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAmB,EAAE,IAAY;IACpE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,qGAAqG;AACrG,mGAAmG;AACnG,wFAAwF;AACxF,MAAM,UAAU,oBAAoB,CAClC,IAAsB,EACtB,GAAW,EACX,MAAwC;IAExC,IAAI,CAAC,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAC1F,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAsB,EAAE,IAAY;IAChE,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,IAA0B,EAC1B,YAAoB;IAEpB,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAwB,EAAE,IAAY;IACpE,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAkB;IAC1C,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,IAAsB,EACtB,OAAe,EACf,IAAuB,EACvB,OAAuC;IAEvC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,IAA0B,EAC1B,YAAoB,EACpB,IAAiC,EACjC,SAAsC;IAEtC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;AACtE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/shell",
-  "version": "0.5.0-next.1944.cd6b6e7",
+  "version": "0.5.1-edge.1047.858b9b6",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,11 +38,12 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.5.0-next.1944.cd6b6e7"
+    "@flighthq/types": "0.5.1-edge.1047.858b9b6"
   },
   "devDependencies": {
+    "@flighthq/entity": "*",
     "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",
+  "description": "OS shell commands over seven explicit Host capability slots with required external URL policy",
   "sideEffects": false
 }

package/src/shell.test.ts

@@ -1,359 +1,296 @@
-import type { ShellBackend, ShellOpenExternalOptions, ShellOpenPathOptions } from '@flighthq/types/contract';
+import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
+import type {
+  EntityRuntimeKey,
+  HasShellBeep,
+  HasShellExternal,
+  HasShellPathOpen,
+  HasShellPathReveal,
+  HasShellShortcutLink,
+  HasShellTrash,
+  ShellBeepBackend,
+  ShellExternalBackend,
+  ShellExternalUrlPolicy,
+  ShellPathOpenBackend,
+  ShellPathRevealBackend,
+  ShellProcess,
+  ShellProcessBackend,
+  ShellProcessHost,
+  ShellProcessOptions,
+  ShellShortcutLinkBackend,
+  ShellTrashBackend,
+} from '@flighthq/types/contract';
 
 import {
-  explainShellBackend,
-  getShellBackend,
-  installShellHostBackend,
   isShellUrlAllowed,
-  moveItemsToTrash,
-  moveItemToTrash,
-  observeShellHostResult,
+  moveShellItemsToTrash,
+  moveShellItemToTrash,
   openShellExternalUrl,
   openShellPath,
-  openShellPathResult,
   readShellShortcutLink,
-  resetShellBackendForTest,
-  setShellBackend,
-  setShellUrlSchemeAllowlist,
+  revealShellPath,
   shellBeep,
-  showItemInFolder,
+  spawnShellProcess,
   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;
-    },
-  };
-}
-
-function resetShellTestState(): void {
-  resetShellBackendForTest();
-  setShellUrlSchemeAllowlist(null);
-}
-
-// The root fast suite deliberately shares modules between files. A host-adapter test can therefore
-// be the state immediately before this file; reset on entry as well as exit so the first assertion has
-// the same isolation as every later one.
-beforeEach(resetShellTestState);
-afterEach(resetShellTestState);
-
-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('returns custom layer when a custom backend is set', () => {
-    setShellBackend(fakeBackend());
-    expect(explainShellBackend().layer).toBe('custom');
+describe('isShellUrlAllowed', () => {
+  it('matches schemes case-insensitively from an explicit policy', () => {
+    expect(isShellUrlAllowed('https://example.test', { allowedSchemes: ['HTTPS'] })).toBe(true);
+    expect(isShellUrlAllowed('mailto:user@example.test', { allowedSchemes: ['https'] })).toBe(false);
   });
 
-  it('returns host layer when a host backend is installed', () => {
-    installShellHostBackend(fakeBackend());
-    expect(explainShellBackend().layer).toBe('host');
+  it('blocks malformed URLs and an empty policy', () => {
+    expect(isShellUrlAllowed('not a URL', { allowedSchemes: ['https'] })).toBe(false);
+    expect(isShellUrlAllowed('https://example.test', { allowedSchemes: [] })).toBe(false);
   });
 });
 
-describe('getShellBackend', () => {
-  it('falls back to sentinel', () => {
-    expect(getShellBackend()).not.toBeNull();
-  });
-
-  it('returns the registered backend', () => {
-    const backend = fakeBackend();
-    setShellBackend(backend);
-    expect(getShellBackend()).toBe(backend);
+describe('moveShellItemsToTrash', () => {
+  it('starts every one-path operation and preserves input order while awaiting all results', async () => {
+    const paths: string[] = [];
+    const resolvers: Array<(outcome: { reason: 'ok' | 'operation-failed' }) => void> = [];
+    const host = trashHost(
+      (() => {
+        const out = allocateEntity<any>();
+        out.moveToTrash = (path: string) => {
+          paths.push(path);
+          return new Promise((resolve) => resolvers.push(resolve));
+        };
+        return finishEntity(out);
+      })(),
+    );
+
+    const outcomes = moveShellItemsToTrash(host, ['/first', '/second']);
+    expect(paths).toEqual(['/first', '/second']);
+    resolvers[1]?.({ reason: 'operation-failed' });
+    let settled = false;
+    void outcomes.then(() => {
+      settled = true;
+    });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    resolvers[0]?.({ reason: 'ok' });
+    await expect(outcomes).resolves.toEqual([{ reason: 'ok' }, { reason: 'operation-failed' }]);
   });
 });
 
-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('moveShellItemToTrash', () => {
+  it('routes through the supplied trash provider', async () => {
+    const moveToTrash = vi.fn(async () => ({ reason: 'ok' as const }));
+    await expect(
+      moveShellItemToTrash(
+        trashHost(
+          (() => {
+            const out = allocateEntity<any>();
+            out.moveToTrash = moveToTrash;
+            return finishEntity(out);
+          })(),
+        ),
+        '/item',
+      ),
+    ).resolves.toEqual({
+      reason: 'ok',
+    });
+    expect(moveToTrash).toHaveBeenCalledWith('/item');
   });
 });
 
-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('openShellExternalUrl', () => {
+  it('requires policy as the third parameter at the type boundary', () => {
+    expectTypeOf(openShellExternalUrl).parameters.toEqualTypeOf<
+      [HasShellExternal, string, Readonly<ShellExternalUrlPolicy>]
+    >();
+  });
+
+  it('blocks before dispatch when the scheme is not allowed', async () => {
+    const open = vi.fn(async () => ({ reason: 'ok' as const }));
+    const host = externalHost(
+      (() => {
+        const out = allocateEntity<any>();
+        out.open = open;
+        return finishEntity(out);
+      })(),
+    );
+    await expect(openShellExternalUrl(host, 'file:///etc/passwd', { allowedSchemes: ['https'] })).resolves.toEqual({
+      reason: 'blocked-scheme',
+    });
+    expect(open).not.toHaveBeenCalled();
+  });
+
+  it('keeps two live hosts isolated', async () => {
+    const calls: string[] = [];
+    const first = externalHost(
+      (() => {
+        const out = allocateEntity<any>();
+        out.open = async (url: string) => {
+          calls.push(`first:${url}`);
+          return { reason: 'ok' };
+        };
+        return finishEntity(out);
+      })(),
+    );
+    const second = externalHost(
+      (() => {
+        const out = allocateEntity<any>();
+        out.open = async (url: string) => {
+          calls.push(`second:${url}`);
+          return { reason: 'operation-failed' };
+        };
+        return finishEntity(out);
+      })(),
+    );
+    await expect(openShellExternalUrl(first, 'https://one.test', HTTPS_ONLY)).resolves.toEqual({ reason: 'ok' });
+    await expect(openShellExternalUrl(second, 'https://two.test', HTTPS_ONLY)).resolves.toEqual({
+      reason: 'operation-failed',
+    });
+    expect(calls).toEqual(['first:https://one.test', 'second:https://two.test']);
   });
 });
 
-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('openShellPath', () => {
+  it('preserves a provider failure and its message', async () => {
+    const provider = allocateEntity<ShellPathOpenBackend>();
+    provider.open = async () => {
+      return { message: '', reason: 'operation-failed' as const };
+    };
+    await expect(openShellPath(pathOpenHost(finishEntity(provider)), '/missing')).resolves.toEqual({
+      message: '',
+      reason: 'operation-failed',
+    });
   });
 });
 
-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('readShellShortcutLink', () => {
+  it('returns the read-specific outcome', async () => {
+    const provider = shortcutLinkProvider();
+    await expect(readShellShortcutLink(shortcutLinkHost(provider), '/app.lnk')).resolves.toEqual({
+      link: { target: '/app' },
+      reason: 'ok',
+    });
   });
 });
 
-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('revealShellPath', () => {
+  it('returns the reveal-specific outcome', async () => {
+    const reveal = vi.fn(async () => ({ reason: 'operation-failed' as const }));
+    await expect(
+      revealShellPath(
+        pathRevealHost(
+          (() => {
+            const out = allocateEntity<any>();
+            out.reveal = reveal;
+            return finishEntity(out);
+          })(),
+        ),
+        '/item',
+      ),
+    ).resolves.toEqual({
+      reason: 'operation-failed',
+    });
   });
 });
 
-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('shellBeep', () => {
+  it('dispatches synchronously', () => {
+    const beep = vi.fn();
+    shellBeep(
+      beepHost(
+        (() => {
+          const out = allocateEntity<any>();
+          out.beep = beep;
+          return finishEntity(out);
+        })(),
+      ),
+    );
+    expect(beep).toHaveBeenCalledOnce();
   });
 });
 
-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');
+describe('spawnShellProcess', () => {
+  it('exposes the explicit host, command, argument-vector, and optional-options API', () => {
+    expectTypeOf(spawnShellProcess).parameters.toEqualTypeOf<
+      [ShellProcessHost, string, readonly string[], Readonly<ShellProcessOptions>?]
+    >();
+    expectTypeOf(spawnShellProcess).returns.toEqualTypeOf<ShellProcess | null>();
   });
 
-  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 command, argument vector, and options to the host backend unchanged', () => {
+    const process = shellProcess();
+    const spawn = vi.fn(() => process);
+    const host = processHost(
+      (() => {
+        const out = allocateEntity<any>();
+        out.spawn = spawn;
+        return finishEntity(out);
+      })(),
+    );
+    const args = ['--flag', 'value'] as const;
+    const options = { cwd: '/work', environment: { MODE: 'test' } } as const;
 
-  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' });
+    expect(spawnShellProcess(host, '/bin/tool', args, options)).toBe(process);
+    expect(spawn).toHaveBeenCalledWith('/bin/tool', args, options);
   });
 
-  it('omits options when none provided', async () => {
-    const backend = fakeBackend();
-    setShellBackend(backend);
-    await openShellPath('/tmp/x');
-    expect(backend.lastOptions).toBeUndefined();
+  it('returns null when the host does not expose child-process support', () => {
+    expect(spawnShellProcess({ shell: {} }, '/bin/tool', [])).toBeNull();
   });
 });
 
-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('writeShellShortcutLink', () => {
+  it('requires an explicit write operation and returns the write-specific outcome', async () => {
+    const provider = shortcutLinkProvider();
+    await expect(
+      writeShellShortcutLink(shortcutLinkHost(provider), '/app.lnk', { target: '/app' }, 'replace'),
+    ).resolves.toEqual({ reason: 'ok' });
+    expect(provider.write).toHaveBeenCalledWith('/app.lnk', { target: '/app' }, 'replace');
   });
 });
 
-describe('readShellShortcutLink', () => {
-  it('returns null with sentinel (no backend set)', async () => {
-    const result = await readShellShortcutLink('/tmp/x.lnk');
-    expect(result).toBeNull();
-  });
+const HTTPS_ONLY: ShellExternalUrlPolicy = { allowedSchemes: ['https'] };
 
-  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' });
-  });
-});
+function beepHost(beep: ShellBeepBackend): HasShellBeep {
+  return { shell: { beep } };
+}
 
-describe('resetShellBackendForTest', () => {
-  it('clears all backend slots', () => {
-    setShellBackend(fakeBackend());
-    installShellHostBackend(fakeBackend());
-    resetShellBackendForTest();
-    expect(explainShellBackend().layer).toBe('host-not-enabled');
-  });
-});
+function externalHost(external: ShellExternalBackend): HasShellExternal {
+  return { shell: { external } };
+}
 
-describe('setShellBackend', () => {
-  it('clears back to sentinel when passed null', () => {
-    setShellBackend(fakeBackend());
-    setShellBackend(null);
-    expect(getShellBackend()).not.toBeNull();
-  });
-});
+function pathOpenHost(pathOpen: ShellPathOpenBackend): HasShellPathOpen {
+  return { shell: { pathOpen } };
+}
 
-describe('setShellUrlSchemeAllowlist', () => {
-  it('allows all URLs when set to null', () => {
-    setShellUrlSchemeAllowlist(['https']);
-    setShellUrlSchemeAllowlist(null);
-    expect(isShellUrlAllowed('file:///tmp/x')).toBe(true);
-  });
+function pathRevealHost(pathReveal: ShellPathRevealBackend): HasShellPathReveal {
+  return { shell: { pathReveal } };
+}
 
-  it('restricts URLs to the listed schemes', () => {
-    setShellUrlSchemeAllowlist(['https', 'mailto']);
-    expect(isShellUrlAllowed('ftp://example.com')).toBe(false);
-  });
-});
+function processHost(process: ShellProcessBackend): ShellProcessHost {
+  return { shell: { process } };
+}
 
-describe('shellBeep', () => {
-  it('forwards to the active backend', () => {
-    const backend = fakeBackend();
-    setShellBackend(backend);
-    shellBeep();
-    expect(backend.beeped).toBe(1);
-  });
-});
+function shellProcess(): ShellProcess {
+  const out = allocateEntity<any>();
+  out.exit = Promise.resolve({ code: 0, signal: null });
+  out.stderr = new ReadableStream<Uint8Array>();
+  out.stdin = new WritableStream<Uint8Array>();
+  out.stdout = new ReadableStream<Uint8Array>();
+  out.terminate = vi.fn();
+  return finishEntity(out);
+}
 
-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');
-  });
-});
+function shortcutLinkHost(shortcutLink: ShellShortcutLinkBackend): HasShellShortcutLink {
+  return { shell: { shortcutLink } };
+}
 
-describe('writeShellShortcutLink', () => {
-  it('returns false with sentinel (no backend set)', async () => {
-    const result = await writeShellShortcutLink('/tmp/x.lnk', { target: '/tmp/target' });
-    expect(result).toBe(false);
-  });
+function shortcutLinkProvider(): ShellShortcutLinkBackend & { write: ReturnType<typeof vi.fn> } {
+  const out = allocateEntity<any>();
+  out.read = async () => {
+    return { link: { target: '/app' }, reason: 'ok' };
+  };
+  out.write = vi.fn(async () => ({ reason: 'ok' as const }));
+  return finishEntity(out);
+}
 
-  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);
-  });
-});
+function trashHost(trash: ShellTrashBackend): HasShellTrash {
+  return { shell: { trash } };
+}