obsidian-launcher 1.3.3 → 2.0.1

package/dist/index.d.ts

@@ -2,18 +2,39 @@ import child_process from 'child_process';
 
 /**
  * Type of the obsidian-versions.json file.
+ * @category Types
  */
-type ObsidianVersionInfos = {
+type ObsidianVersionList = {
     metadata: {
+        schemaVersion: string;
         commitDate: string;
         commitSha: string;
         timestamp: string;
     };
     versions: ObsidianVersionInfo[];
 };
+/**
+ * Metadata about a specific Obsidian desktop installer.
+ * @category Types
+ */
+type ObsidianInstallerInfo = {
+    /**
+     * Hash of the file content.
+     * For releases from before GitHub started storing digests, this will be set to file "id" which also changes if the
+     * file is updated.
+     */
+    digest: string;
+    /** Electron version */
+    electron: string;
+    /** Chrome version */
+    chrome: string;
+    /** platform-arch combinations supported by the installer */
+    platforms: string[];
+};
 /**
  * Metadata about a specific Obsidian version, including the min/max compatible installer versions, download urls, and
- * the internal electron version.
+ * the internal Electron version.
+ * @category Types
  */
 type ObsidianVersionInfo = {
     version: string;
@@ -25,16 +46,28 @@ type ObsidianVersionInfo = {
         asar?: string;
         appImage?: string;
         appImageArm?: string;
-        apk?: string;
+        tar?: string;
+        tarArm?: string;
         dmg?: string;
         exe?: string;
+        apk?: string;
+    };
+    installers: {
+        appImage?: ObsidianInstallerInfo;
+        appImageArm?: ObsidianInstallerInfo;
+        tar?: ObsidianInstallerInfo;
+        tarArm?: ObsidianInstallerInfo;
+        dmg?: ObsidianInstallerInfo;
+        exe?: ObsidianInstallerInfo;
     };
+    /** @deprecated Use installers instead */
     electronVersion?: string;
+    /** @deprecated Use installers instead */
     chromeVersion?: string;
-    nodeVersion?: string;
 };
 /**
  * Schema of entries in https://github.com/obsidianmd/obsidian-releases/blob/HEAD/community-plugins.json
+ * @category Types
  */
 type ObsidianCommunityPlugin = {
     id: string;
@@ -45,6 +78,7 @@ type ObsidianCommunityPlugin = {
 };
 /**
  * Schema of entries in https://github.com/obsidianmd/obsidian-releases/blob/HEAD/community-css-themes.json
+ * @category Types
  */
 type ObsidianCommunityTheme = {
     name: string;
@@ -54,29 +88,29 @@ type ObsidianCommunityTheme = {
     modes: string[];
 };
 /** @inline */
-type BasePluginEntry = {
+interface BasePluginEntry {
     /** Set false to install the plugin but start it disabled. Default true. */
     enabled?: boolean;
-};
+}
 /** @inline */
-type LocalPluginEntry = BasePluginEntry & {
+interface LocalPluginEntry extends BasePluginEntry {
     /** Path on disk to the plugin to install. */
     path: string;
-};
+}
 /** @inline */
-type GitHubPluginEntry = BasePluginEntry & {
+interface GitHubPluginEntry extends BasePluginEntry {
     /** Github repo of the plugin to install, e.g. "some-user/some-plugin". */
     repo: string;
     /** Version of the plugin to install. Defaults to latest. */
     version?: string;
-};
+}
 /** @inline */
-type CommunityPluginEntry = BasePluginEntry & {
+interface CommunityPluginEntry extends BasePluginEntry {
     /** Plugin ID to install from Obsidian community plugins. */
     id: string;
     /** Version of the plugin to install. Defaults to latest. */
     version?: string;
-};
+}
 /**
  * A plugin to install. Can be a simple string path to the local plugin to install, or an object.
  * If an object set one of:
@@ -85,8 +119,14 @@ type CommunityPluginEntry = BasePluginEntry & {
  * - `id` to install a community plugin
  *
  * You can also pass `enabled: false` to install the plugin, but start it disabled by default.
+ *
+ * @category Types
  */
 type PluginEntry = string | LocalPluginEntry | GitHubPluginEntry | CommunityPluginEntry;
+/**
+ * PluginEntry plus downloaded path.
+ * @category Types
+ */
 type DownloadedPluginEntry = {
     /** If the plugin is enabled */
     enabled: boolean;
@@ -98,28 +138,28 @@ type DownloadedPluginEntry = {
     originalType: "local" | "github" | "community";
 };
 /** @inline */
-type BaseThemeEntry = {
+interface BaseThemeEntry {
     /**
      * Set false to install the theme but not enable it. Defaults to true.
      * Only one theme can be enabled.
      */
     enabled?: boolean;
-};
+}
 /** @inline */
-type LocalThemeEntry = BaseThemeEntry & {
+interface LocalThemeEntry extends BaseThemeEntry {
     /** Path on disk to the theme to install. */
     path: string;
-};
+}
 /** @inline */
-type GitHubThemeEntry = BaseThemeEntry & {
+interface GitHubThemeEntry extends BaseThemeEntry {
     /** Github repo of the theme to install, e.g. "some-user/some-theme". */
     repo: string;
-};
+}
 /** @inline */
-type CommunityThemeEntry = BaseThemeEntry & {
+interface CommunityThemeEntry extends BaseThemeEntry {
     /** Theme name to install from Obsidian community themes. */
     name: string;
-};
+}
 /**
  * A theme to install. Can be a simple string path to the local theme to install, or an object.
  * If an object, set one of:
@@ -129,8 +169,14 @@ type CommunityThemeEntry = BaseThemeEntry & {
  *
  * You can also pass `enabled: false` to install the theme, but start it disabled by default. You can only have one
  * enabled theme, so if you pass multiple you need to disable all but one.
+ *
+ * @category Types
  */
 type ThemeEntry = string | LocalThemeEntry | GitHubThemeEntry | CommunityThemeEntry;
+/**
+ * ThemeEntry plus downloaded path.
+ * @category Types
+ */
 type DownloadedThemeEntry = {
     /** If the theme is enabled */
     enabled: boolean;
@@ -156,20 +202,24 @@ declare class ObsidianLauncher {
     readonly cacheDuration: number;
     /** Cached metadata files and requests */
     private metadataCache;
+    readonly interactive: boolean;
+    private obsidianApiToken;
     /**
      * Construct an ObsidianLauncher.
-     * @param options.cacheDir Path to the cache directory. Defaults to "OBSIDIAN_CACHE" env var or ".obsidian-cache".
-     * @param options.versionsUrl Custom `obsidian-versions.json` url. Can be a file URL.
-     * @param options.communityPluginsUrl Custom `community-plugins.json` url. Can be a file URL.
-     * @param options.communityThemesUrl Custom `community-css-themes.json` url. Can be a file URL.
-     * @param options.cacheDuration If the cached version list is older than this (in ms), refetch it. Defaults to 30 minutes.
+     * @param opts.cacheDir Path to the cache directory. Defaults to "OBSIDIAN_CACHE" env var or ".obsidian-cache".
+     * @param opts.versionsUrl Custom `obsidian-versions.json` url. Can be a file URL.
+     * @param opts.communityPluginsUrl Custom `community-plugins.json` url. Can be a file URL.
+     * @param opts.communityThemesUrl Custom `community-css-themes.json` url. Can be a file URL.
+     * @param opts.cacheDuration If the cached version list is older than this (in ms), refetch it. Defaults to 30 minutes.
+     * @param opts.interactive If it can prompt the user for input (e.g. for Obsidian credentials). Default false.
      */
-    constructor(options?: {
+    constructor(opts?: {
         cacheDir?: string;
         versionsUrl?: string;
         communityPluginsUrl?: string;
         communityThemesUrl?: string;
         cacheDuration?: number;
+        interactive?: boolean;
     });
     /**
      * Returns file content fetched from url as JSON. Caches content to dest and uses that cache if its more recent than
@@ -194,11 +244,11 @@ declare class ObsidianLauncher {
     getCommunityThemes(): Promise<ObsidianCommunityTheme[]>;
     /**
      * Resolves Obsidian app and installer version strings to absolute versions.
-     * @param appVersion Obsidian version string or one of
+     * @param appVersion specific version or one of
      *   - "latest": Get the current latest non-beta Obsidian version
      *   - "latest-beta": Get the current latest beta Obsidian version (or latest is there is no current beta)
      *   - "earliest": Get the `minAppVersion` set in your `manifest.json`
-     * @param installerVersion Obsidian version string or one of
+     * @param installerVersion specific version or one of
      *   - "latest": Get the latest Obsidian installer compatible with `appVersion`
      *   - "earliest": Get the oldest Obsidian installer compatible with `appVersion`
      *
@@ -206,27 +256,59 @@ declare class ObsidianLauncher {
      *
      * @returns [appVersion, installerVersion] with any "latest" etc. resolved to specific versions.
      */
-    resolveVersions(appVersion: string, installerVersion?: string): Promise<[string, string]>;
+    resolveVersion(appVersion: string, installerVersion?: string): Promise<[string, string]>;
     /**
      * Gets details about an Obsidian version.
      * @param appVersion Obsidian app version
      */
     getVersionInfo(appVersion: string): Promise<ObsidianVersionInfo>;
     /**
-     * Downloads the Obsidian installer for the given version and current platform. Returns the file path.
-     * @param installerVersion Obsidian installer version to download
+     * Parses a string of Obsidian versions into [appVersion, installerVersion] tuples.
+     *
+     * `versions` should be a space separated list of Obsidian app versions. You can optionally specify the installer
+     * version by using "appVersion/installerVersion" e.g. `"1.7.7/1.8.10"`.
+     *
+     * Example:
+     * ```js
+     * launcher.parseVersions("1.8.10/1.7.7 latest latest-beta/earliest")
+     * ```
+     *
+     * See also: [Obsidian App vs Installer Versions](../README.md#obsidian-app-vs-installer-versions)
+     *
+     * @param versions string to parse
+     * @returns [appVersion, installerVersion][] resolved to specific versions.
      */
-    downloadInstaller(installerVersion: string): Promise<string>;
+    parseVersions(versions: string): Promise<[string, string][]>;
+    private getInstallerKey;
     /**
-     * Helper for downloadInstaller that doesn't require the obsidian-versions.json file so it can be used in
-     * updateObsidianVersionInfos
+     * Gets details about the Obsidian installer for the given platform.
+     * @param installerVersion Obsidian installer version
+     * @param opts.platform Platform/os (defaults to host platform)
+     * @param opts.arch Architecture (defaults to host architecture)
+     */
+    getInstallerInfo(installerVersion: string, opts?: {
+        platform?: NodeJS.Platform;
+        arch?: NodeJS.Architecture;
+    }): Promise<ObsidianInstallerInfo & {
+        url: string;
+    }>;
+    /**
+     * Downloads the Obsidian installer for the given version and platform/arch (defaults to host platform/arch).
+     * Returns the file path.
+     * @param installerVersion Obsidian installer version to download
+     * @param opts.platform Platform/os of the installer to download (defaults to host platform)
+     * @param opts.arch Architecture of the installer to download (defaults to host architecture)
      */
-    private downloadInstallerFromVersionInfo;
+    downloadInstaller(installerVersion: string, opts?: {
+        platform?: NodeJS.Platform;
+        arch?: NodeJS.Architecture;
+    }): Promise<string>;
     /**
      * Downloads the Obsidian asar for the given version. Returns the file path.
      *
-     * To download beta versions you'll need to have an Obsidian account with Catalyst and set the `OBSIDIAN_USERNAME`
-     * and `OBSIDIAN_PASSWORD` environment variables. 2FA needs to be disabled.
+     * To download Obsidian beta versions you'll need have an Obsidian Insiders account and either set the
+     * `OBSIDIAN_EMAIL` and `OBSIDIAN_PASSWORD` env vars (`.env` is supported) or pre-download the Obsidian beta with
+     * `npx obsidian-launcher download -v latest-beta`
      *
      * @param appVersion Obsidian version to download
      */
@@ -242,7 +324,14 @@ declare class ObsidianLauncher {
      *
      * @param installerVersion Obsidian installer version
      */
-    downloadChromedriver(installerVersion: string): Promise<string>;
+    downloadChromedriver(installerVersion: string, opts?: {
+        platform?: NodeJS.Platform;
+        arch?: NodeJS.Architecture;
+    }): Promise<string>;
+    /**
+     * Downloads the Obsidian apk.
+     */
+    downloadAndroid(version: string): Promise<string>;
     /** Gets the latest version of a plugin. */
     private getLatestPluginVersion;
     /**
@@ -260,8 +349,8 @@ declare class ObsidianLauncher {
      */
     private downloadCommunityPlugin;
     /**
-     * Downloads a list of plugins to the cache and returns a list of `DownloadedPluginEntry` with the downloaded paths.
-     * Also adds the `id` property to the plugins based on the manifest.
+     * Downloads a list of plugins to the cache and returns a list of {@link DownloadedPluginEntry} with the downloaded
+     * paths. Also adds the `id` property to the plugins based on the manifest.
      *
      * You can download plugins from GitHub using `{repo: "org/repo"}` and community plugins using `{id: 'plugin-id'}`.
      * Local plugins will just be passed through.
@@ -284,8 +373,8 @@ declare class ObsidianLauncher {
      */
     private downloadCommunityTheme;
     /**
-     * Downloads a list of themes to the cache and returns a list of `DownloadedThemeEntry` with the downloaded paths.
-     * Also adds the `name` property to the plugins based on the manifest.
+     * Downloads a list of themes to the cache and returns a list of {@link DownloadedThemeEntry} with the downloaded
+     * paths. Also adds the `name` property to the plugins based on the manifest.
      *
      * You can download themes from GitHub using `{repo: "org/repo"}` and community themes using `{name: 'theme-name'}`.
      * Local themes will just be passed through.
@@ -311,15 +400,17 @@ declare class ObsidianLauncher {
      * @param params.appVersion Obsidian app version
      * @param params.installerVersion Obsidian version string.
      * @param params.appPath Path to the asar file to install. Will download if omitted.
-     * @param params.vault Path to the vault to open in Obsidian.
-     * @param params.dest Destination path for the config dir. If omitted it will create a temporary directory.
+     * @param params.vault Path to the vault to open in Obsidian
+     * @param params.localStorage items to add to localStorage. `$vaultId` in the keys will be replaced with the vaultId
+     * @param params.chromePreferences Chrome preferences to add to the Preferences file
      */
     setupConfigDir(params: {
         appVersion: string;
         installerVersion: string;
         appPath?: string;
         vault?: string;
-        dest?: string;
+        localStorage?: Record<string, string>;
+        chromePreferences?: Record<string, any>;
     }): Promise<string>;
     /**
      * Sets up a vault for Obsidian, installing plugins and themes and optionally copying the vault to a temporary
@@ -340,8 +431,6 @@ declare class ObsidianLauncher {
      * Downloads and launches Obsidian with a sandboxed config dir and a specifc vault open. Optionally install plugins
      * and themes first.
      *
-     * This is just a shortcut for calling `downloadApp`, `downloadInstaller`, `setupVault` and `setupConfDir`.
-     *
      * @param params.appVersion Obsidian app version. Default "latest"
      * @param params.installerVersion Obsidian installer version. Default "latest"
      * @param params.vault Path to the vault to open in Obsidian
@@ -349,6 +438,7 @@ declare class ObsidianLauncher {
      * @param params.plugins List of plugins to install in the vault
      * @param params.themes List of themes to install in the vault
      * @param params.args CLI args to pass to Obsidian
+     * @param params.localStorage items to add to localStorage. `$vaultId` in the keys will be replaced with the vaultId
      * @param params.spawnOptions Options to pass to `spawn`
      * @returns The launched child process and the created tmpdirs
      */
@@ -360,6 +450,7 @@ declare class ObsidianLauncher {
         plugins?: PluginEntry[];
         themes?: ThemeEntry[];
         args?: string[];
+        localStorage?: Record<string, string>;
         spawnOptions?: child_process.SpawnOptions;
     }): Promise<{
         proc: child_process.ChildProcess;
@@ -367,13 +458,13 @@ declare class ObsidianLauncher {
         vault?: string;
     }>;
     /**
-     * Updates the info obsidian-versions.json. The obsidian-versions.json file is used in other launcher commands
+     * Updates the info in obsidian-versions.json. The obsidian-versions.json file is used in other launcher commands
      * and in wdio-obsidian-service to get metadata about Obsidian versions in one place such as minInstallerVersion and
-     * the internal electron version.
+     * the internal Electron version.
      */
-    updateObsidianVersionInfos(original?: ObsidianVersionInfos, { maxInstances }?: {
-        maxInstances?: number | undefined;
-    }): Promise<ObsidianVersionInfos>;
+    updateVersionList(original?: ObsidianVersionList, opts?: {
+        maxInstances?: number;
+    }): Promise<ObsidianVersionList>;
     /**
      * Returns true if the Obsidian version is already in the cache.
      * @param type on of "app" or "installer"
@@ -393,4 +484,4 @@ declare class ObsidianLauncher {
  * @document ../README.md
  */
 
-export { type DownloadedPluginEntry, type DownloadedThemeEntry, type ObsidianCommunityPlugin, type ObsidianCommunityTheme, type ObsidianVersionInfo, type ObsidianVersionInfos, type PluginEntry, type ThemeEntry, ObsidianLauncher as default };
+export { type DownloadedPluginEntry, type DownloadedThemeEntry, type ObsidianCommunityPlugin, type ObsidianCommunityTheme, type ObsidianInstallerInfo, type ObsidianVersionInfo, type ObsidianVersionList, type PluginEntry, type ThemeEntry, ObsidianLauncher as default };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   ObsidianLauncher
-} from "./chunk-MZRDQQTK.js";
+} from "./chunk-KPNJCYO4.js";
 
 // src/index.ts
 var index_default = ObsidianLauncher;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @module\n * @document ../README.md\n */\nimport { ObsidianLauncher } from \"./launcher.js\"\n\nexport default ObsidianLauncher;\nexport type {\n    ObsidianVersionInfos, ObsidianVersionInfo, ObsidianCommunityPlugin, ObsidianCommunityTheme,\n    PluginEntry, DownloadedPluginEntry, ThemeEntry, DownloadedThemeEntry,\n} from \"./types.js\";\n"],"mappings":";;;;;AAMA,IAAO,gBAAQ;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @module\n * @document ../README.md\n */\nimport { ObsidianLauncher } from \"./launcher.js\"\n\nexport default ObsidianLauncher;\nexport type {\n    ObsidianVersionList, ObsidianVersionInfo, ObsidianInstallerInfo, ObsidianCommunityPlugin, ObsidianCommunityTheme,\n    PluginEntry, DownloadedPluginEntry, ThemeEntry, DownloadedThemeEntry,\n} from \"./types.js\";\n"],"mappings":";;;;;AAMA,IAAO,gBAAQ;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "obsidian-launcher",
-    "version": "1.3.3",
+    "version": "2.0.1",
     "description": "Download and launch sandboxed Obsidian instances",
     "keywords": [
         "obsidian"
@@ -27,7 +27,8 @@
     "scripts": {
         "build": "tsup",
         "test": "run-s test:*",
-        "test:unit": "tsc --noEmit && mocha"
+        "test:unit": "tsc --noEmit && mocha --config .mocharc.unit.json",
+        "test:e2e": "tsc --noEmit && mocha --config .mocharc.e2e.json"
     },
     "repository": {
         "type": "git",
@@ -41,30 +42,38 @@
     },
     "homepage": "https://jesse-r-s-hines.github.io/wdio-obsidian-service/obsidian-launcher/README.html",
     "devDependencies": {
-        "@types/chai": "^5.0.1",
+        "@types/chai": "^5.2.2",
         "@types/chrome-remote-interface": "^0.31.14",
-        "@types/lodash": "^4.17.14",
+        "@types/cross-spawn": "^6.0.6",
+        "@types/lodash": "^4.17.20",
         "@types/mocha": "^10.0.10",
-        "@types/node": "^18.11.9",
-        "@types/semver": "^7.5.8",
-        "chai": "^5.1.2",
-        "mocha": "^11.0.1",
+        "@types/node": "^18.19.121",
+        "@types/readline-sync": "^1.4.8",
+        "@types/semver": "^7.7.0",
+        "@types/serve-handler": "^6.1.4",
+        "chai": "^5.2.1",
+        "mocha": "^11.7.1",
         "npm-run-all": "^4.1.5",
+        "serve": "^14.2.4",
+        "serve-handler": "^6.1.6",
+        "ts-essentials": "^10.1.1",
         "ts-node": "^10.9.2",
-        "tsup": "^8.3.5",
-        "tsx": "^4.19.2",
-        "typescript": "^5.8.2"
+        "tsup": "^8.5.0",
+        "tsx": "^4.20.3",
+        "typescript": "^5.8.3"
     },
     "dependencies": {
         "@electron/get": "^3.1.0",
         "@supercharge/promise-pool": "^3.2.0",
-        "chrome-remote-interface": "^0.33.2",
-        "classic-level": "^2.0.0",
-        "commander": "^13.0.0",
+        "7z-wasm": "1.2.0",
+        "chrome-remote-interface": "^0.33.3",
+        "classic-level": "^3.0.0",
+        "commander": "^13.1.0",
+        "dotenv": "^17.2.1",
         "extract-zip": "^2.0.1",
         "lodash": "^4.17.21",
-        "semver": "^7.6.3",
-        "which": "^5.0.0"
+        "readline-sync": "^1.4.10",
+        "semver": "^7.7.2"
     },
     "engines": {
         "node": ">=18"