obsidian-integration-testing 8.3.0 → 9.0.0

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

@@ -16,6 +16,7 @@
  *
  * 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';
@@ -75,6 +76,16 @@ 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
@@ -141,6 +152,7 @@ export declare class DesktopCdpTransport implements ObsidianTransport {
      */
     readonly isMobile = false;
     private activeVaultPath;
+    private asarFallback;
     private readonly cdpHost;
     private cdpPort;
     private cdpUrl;
@@ -153,6 +165,7 @@ export declare class DesktopCdpTransport implements ObsidianTransport {
     private readonly ownedConfig;
     private ownedInstance;
     private readonly shouldDisableSandbox;
+    private readonly shouldThrowOnSilentAsarFallback;
     private readonly shouldWarnOnCompatibilityIssues;
     private ws;
     /**
@@ -185,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
@@ -239,24 +265,46 @@ export declare class DesktopCdpTransport implements ObsidianTransport {
      */
     unregisterVault(vaultPath: string): Promise<void>;
     /**
-     * Best-effort tier-2 runtime nag: reads the live Electron version and running
-     * app version from the booted owned renderer and warns when the Electron the
-     * instance is actually running is older than the app's recommended minimum.
-     * Stores the verdict on {@link getElectronCompatibility}.
-     *
-     * The app version is read **live** — the running app version from the main
-     * process (`ipcRenderer.sendSync('version')`, the same IPC channel the namespace
-     * bootstrap uses) rather than from the resolved config — so the nag reflects the
-     * version genuinely running across every owned sub-path (asar-swap / downgrade /
-     * own-installer) and stays truthful even under a silent asar fallback.
-     * `process.versions.electron` gives the shell's live Electron. Both are read at
-     * the renderer top level (no `require('obsidian')`, which resolves only inside a
-     * plugin-load context). Never throws — a read failure is logged and ignored, so
-     * it cannot break an otherwise-ready boot.
+     * 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 checkRuntimeElectronCompatibility;
+    private checkRuntimeCompatibility;
     /**
      * Connects to a CDP target's WebSocket endpoint.
      *
@@ -320,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