obsidian-integration-testing 8.2.1 → 8.4.0

package/dist/lib/cjs/transport-desktop-cdp.d.cts

@@ -16,6 +16,8 @@
  *
  * Requirements: Node.js 22+ (uses built-in `WebSocket` and `fetch` globals).
  */
+import type { AsarFallback } from './asar-fallback-detection.cjs';
+import type { ElectronCompatibility } from './electron-compatibility.cjs';
 import type { InstallerCompatibility } from './installer-compatibility.cjs';
 import type { ObsidianTransport, TransportEvalOptions } from './transport.cjs';
 /**
@@ -74,6 +76,25 @@ export interface DesktopCdpTransportConfig {
      * @default `false`
      */
     shouldDisableSandbox?: boolean;
+    /**
+     * Whether a post-boot **silent asar fallback** (the running app version differs
+     * from the swapped-in pin) fails fast with {@link SilentAsarFallbackError}. The
+     * verdict is always computed and surfaced via
+     * {@link DesktopCdpTransport.getAsarFallback}; this gates only the throw. Only
+     * meaningful in owned mode running a swapped-in asar.
+     *
+     * @default `true`
+     */
+    shouldThrowOnSilentAsarFallback?: boolean;
+    /**
+     * Whether the post-boot runtime-Electron compatibility nag warning is emitted
+     * when the live Electron is below the app's recommended minimum. The verdict is
+     * always computed and surfaced via {@link DesktopCdpTransport.getElectronCompatibility};
+     * this only gates the log. Only meaningful in owned mode.
+     *
+     * @default `true`
+     */
+    shouldWarnOnCompatibilityIssues?: boolean;
 }
 /**
  * An asar to provision into a harness-owned instance's user-data dir before launch.
@@ -96,7 +117,10 @@ export interface OwnedInstanceConfig {
     /**
      * The resolved installer↔app compatibility verdict, when it could be determined
      * (an asar-swap onto a known shell version). Surfaced by
-     * {@link DesktopCdpTransport.getCompatibility}.
+     * {@link DesktopCdpTransport.getCompatibility}. An `'unrunnable'` verdict reaches
+     * this surface only when the proactive throw is disabled
+     * (`shouldThrowOnIncompatibleInstaller: false`); otherwise it throws
+     * `IncompatibleInstallerVersionError` before the config is built.
      */
     readonly compatibility?: InstallerCompatibility | undefined;
     /** Absolute path to the Obsidian shell executable to launch. */
@@ -128,17 +152,21 @@ export declare class DesktopCdpTransport implements ObsidianTransport {
      */
     readonly isMobile = false;
     private activeVaultPath;
+    private asarFallback;
     private readonly cdpHost;
     private cdpPort;
     private cdpUrl;
     private readonly commandTimeoutInMilliseconds;
     private readonly deadBootGraceInMilliseconds;
+    private electronCompatibility;
     private readonly isHarnessOwnedInstance;
     private readonly isObsidianAppVisible;
     private messageId;
     private readonly ownedConfig;
     private ownedInstance;
     private readonly shouldDisableSandbox;
+    private readonly shouldThrowOnSilentAsarFallback;
+    private readonly shouldWarnOnCompatibilityIssues;
     private ws;
     /**
      * Creates a new CDP transport.
@@ -170,6 +198,19 @@ export declare class DesktopCdpTransport implements ObsidianTransport {
      * @returns The normalized result string.
      */
     evaluate(expression: string, options: TransportEvalOptions): Promise<string>;
+    /**
+     * Returns the silent-asar-fallback verdict for this owned instance — whether the
+     * app version it is actually running matches the swapped-in pin, or the installer
+     * silently reverted to its own bundled asar (read live post-boot). Returns
+     * `undefined` when this is not an owned instance, the instance has not booted
+     * yet, or the verdict could not be determined (no asar was swapped, or the live
+     * version was unreadable). A `'fallback'` verdict reaches this surface only when
+     * the throw is disabled ({@link DesktopCdpTransportConfig.shouldThrowOnSilentAsarFallback}
+     * `false`); otherwise it throws `SilentAsarFallbackError`.
+     *
+     * @returns The silent-asar-fallback verdict, or `undefined`.
+     */
+    getAsarFallback(): AsarFallback | undefined;
     /**
      * Returns the resolved installer↔app compatibility verdict for this owned
      * instance, so callers can assert on it. Returns `undefined` when this is not
@@ -179,6 +220,17 @@ export declare class DesktopCdpTransport implements ObsidianTransport {
      * @returns The compatibility verdict, or `undefined`.
      */
     getCompatibility(): InstallerCompatibility | undefined;
+    /**
+     * Returns the runtime Electron compatibility verdict for this owned instance —
+     * whether the Electron version it is actually running is new enough for the
+     * running app version (read live post-boot; see {@link ObsidianVersionMetadata.minRecommendedElectronVersion}).
+     * Returns `undefined` when this is not an owned instance, the instance has not
+     * booted yet, or the verdict could not be determined (the live version was
+     * unreadable, or the app version carries no recommended Electron version).
+     *
+     * @returns The runtime Electron compatibility verdict, or `undefined`.
+     */
+    getElectronCompatibility(): ElectronCompatibility | undefined;
     /**
      * Returns the CDP endpoint of the owned, launched instance so the global setup
      * can hand it to test workers (which then **attach** to it instead of
@@ -212,6 +264,47 @@ export declare class DesktopCdpTransport implements ObsidianTransport {
      * @param vaultPath - The absolute path to the vault folder.
      */
     unregisterVault(vaultPath: string): Promise<void>;
+    /**
+     * Computes and stores the runtime-Electron compatibility verdict (on
+     * {@link getElectronCompatibility}) from an already-read version pair, warning
+     * when the live Electron is below the app's recommended minimum. Never throws; a
+     * boot whose running app version was unreadable is skipped (nothing to judge).
+     *
+     * @param appVersion - The live running app version, or `undefined` when unreadable.
+     * @param actualElectronVersion - The live Electron version, or `undefined` when unreadable.
+     */
+    private applyElectronCompatibility;
+    /**
+     * Verifies the running app (asar) version matches the swapped-in pin, storing the
+     * verdict on {@link getAsarFallback}. On a **silent fallback** (the installer ran
+     * its own bundled asar instead of the pin) it throws {@link SilentAsarFallbackError}
+     * when the throw is enabled, otherwise warns (when warnings are on) and lets the
+     * boot proceed. A boot with no swapped-in asar, or an unreadable running version,
+     * is `'unknown'` — nothing is thrown or warned. This is the healthy-UI companion to
+     * the black-screen {@link RendererFailedToInitializeError} dead-boot fast-fail.
+     *
+     * @param runningApiVersion - The live running app version, or `undefined` when unreadable.
+     */
+    private checkRuntimeAsarFallback;
+    /**
+     * Runs the post-boot runtime compatibility checks for an owned instance, once the
+     * vault is ready. Reads the live running app version and Electron version **once**
+     * from the booted renderer's main process, then: (1) verifies the running app
+     * version matches the swapped-in pin — throwing {@link SilentAsarFallbackError} on
+     * a silent fallback (when enabled); and (2) runs the best-effort runtime-Electron
+     * nag. Only the asar-fallback check can throw, so this must run outside the
+     * readiness poll's try/catch (a swallowed throw would loop until timeout).
+     *
+     * Both are read at the renderer top level: `ipcRenderer.sendSync('version')` (the
+     * running app version, truthful even under a silent asar fallback) and
+     * `process.versions.electron` (the live shell Electron); neither uses
+     * `require('obsidian')`, which resolves only inside a plugin-load context. A read
+     * failure leaves both unknown (logged, non-fatal) — an unreadable running version
+     * cannot be judged a fallback, so the boot is not broken by a flaky read.
+     *
+     * @param vaultPath - The vault path to evaluate in.
+     */
+    private checkRuntimeCompatibility;
     /**
      * Connects to a CDP target's WebSocket endpoint.
      *
@@ -275,6 +368,17 @@ export declare class DesktopCdpTransport implements ObsidianTransport {
      * @returns The list of page targets.
      */
     private getPageTargets;
+    /**
+     * Kills the currently-running owned instance (if any) and waits for it to exit,
+     * so the next launch gets a pristine single-window instance.
+     *
+     * Relaunching over a live instance is forwarded by Electron's single-instance
+     * lock on the shared user-data dir and surfaces the vault picker, and opening a
+     * second window via IPC leaves stale windows that break vault-target routing —
+     * hence a full kill + wait-for-exit (releasing the lock) between launches. A
+     * no-op on the first attempt, when no instance is running yet.
+     */
+    private killRunningOwnedInstance;
     /**
      * Moves the owned instance's window off-screen so a hidden run never steals
      * focus. Uses Electron's remote bridge (`window.electron.remote`) — the only