obsidian-integration-testing 15.0.0 → 17.0.0

package/dist/lib/cjs/transport-appium.d.cts

@@ -303,7 +303,11 @@ export declare class AppiumTransport implements ObsidianTransport {
      * Registers a vault on mobile by pushing files and configuring localStorage.
      *
      * The registration flow:
-     * 1. Push a minimal `.obsidian/app.json` to the device so Obsidian recognizes the vault
+     * 1. Push a minimal `.obsidian/app.json` to the device so Obsidian recognizes the vault —
+     *    **unless one is already there**, which is the usual case, since `register` pushes the
+     *    whole vault first and that carries the run's real `app.json` across. See
+     *    {@link pushObsidianMarker}: the marker is a truncating overwrite, so pushing it
+     *    unconditionally destroyed the headless defaults it had just been handed.
      * 2. Switch to the WebView context
      * 3. Add the vault to localStorage (`mobile-external-vaults`, `mobile-selected-vault`,
      *    `enable-plugin-<path>`)
@@ -398,6 +402,19 @@ export declare class AppiumTransport implements ObsidianTransport {
      * @param payload - The raw JSON payload the binding was called with.
      */
     private handleInputRequest;
+    /**
+     * Answers whether the device already holds a usable `app.json` at the given path.
+     *
+     * Reads the file rather than testing for it, for the reason
+     * {@link pushObsidianMarker} spells out: only output that parses as a JSON
+     * **object** counts as present, so a merged stderr, an empty file, or a read that
+     * failed outright all answer `false` and let the caller push. Never throws — a
+     * probe that cannot answer is an answer of `false`.
+     *
+     * @param remoteMarker - The device-side `app.json` path.
+     * @returns `true` when the device holds an `app.json` that parses as a JSON object.
+     */
+    private hasDeviceAppJson;
     /**
      * Probes the WebView once for how far Obsidian's startup has got.
      *
@@ -409,13 +426,43 @@ export declare class AppiumTransport implements ObsidianTransport {
      */
     private probeStartup;
     /**
-     * Pushes the minimal `.obsidian/app.json` vault marker via `adb push`.
+     * Pushes the minimal `.obsidian/app.json` vault marker via `adb push` — but
+     * only over a device that has not got one already.
      *
      * `browser.pushFile` (WebDriver base64) is an order of magnitude slower on a
      * cold or loaded emulator — measured at 9–21s per call for this 2-byte marker,
      * versus sub-second over `adb`. This mirrors {@link pushFiles}, which switched
      * to `adb` for the same reason. `mkdir -p` guarantees the parent directory.
      *
+     * ### Why it has to skip rather than always push
+     *
+     * `adb push` is a **truncating overwrite**, not a merge, and the marker is `{}`.
+     * `register` runs {@link pushFiles} first, which tars the whole host vault —
+     * dotfiles included — so by the time this runs the device is already holding the
+     * real `app.json` `ensureHeadlessVaultConfig` wrote for this run. Pushing the
+     * marker over it threw `alwaysUpdateLinks: true` away one call after it arrived,
+     * and Obsidian then opened the vault with the shipped default (off): every
+     * Android rename that touched links stopped on the interactive *"Update links?"*
+     * sheet, hanging the singleton `FileManager.updateQueue` behind it. That is the
+     * rename wall `src/headless-vault-config.ts` exists to remove, live on Android
+     * only, from 6.0.0 (when this push arrived) to 16.0.1. It cost two projects
+     * several runs apiece, and it surfaced as `EvalCapExceededError` naming the
+     * transport cap, which sends the reader after the waiting rather than the sheet.
+     *
+     * The marker exists solely to make Obsidian **recognize** the directory as a
+     * vault, and a real `app.json` does that better than `{}` does. So an existing
+     * one is left exactly as it is.
+     *
+     * ### Why the probe is `cat` and not the teardown's `ls -d`
+     *
+     * `adb shell` merges the device's stderr into stdout on a legacy shell protocol,
+     * and `ls`'s failure message *contains the path it was asked about* — so an
+     * `includes(path)` test can read **absent** as **present**, skip the push, and
+     * leave a genuinely unmarked vault that Obsidian will not open. Reading the file
+     * instead makes the ambiguity harmless: an error message does not parse as a JSON
+     * object, so anything unexpected falls through to the push, which is exactly the
+     * behaviour this replaces.
+     *
      * @param deviceVaultPath - The device-side vault directory path.
      */
     private pushObsidianMarker;