obsidian-launcher 0.3.1 → 0.4.0

package/README.md

@@ -1,3 +1,133 @@
 # obsidian-launcher
 
-TODO
+`obsidian-launcher` is a package for downloading and launching different versions of [Obsidian](https://obsidian.md)
+during testing and development of Obsidian plugins. It can download Obsidian, install plugins and themes into Obsidian
+vaults, and launch sandboxed instances Obsidian with isolated user configuration directories. You can use it either as
+a JavaScript package or as a command line interface.
+
+The primary use case for this package is downloading and launching Obsidian for testing Obsidian plugins
+in WebdriverIO with
+[wdio-obsidian-service](https://jesse-r-s-hines.github.io/wdio-obsidian-service/modules/obsidian-launcher.html). 
+However, it can also be used as a stand-alone package, for instance if you want to test plugins with a different
+ testing framework, or just want to use the provided CLI.
+
+## Example Usage
+The default export of the package is the `ObsidianLauncher` class, which can be used like so:
+```js
+const launcher = new ObsidianLauncher();
+const {proc} = await launcher.launch({
+    appVersion: "1.7.7",
+    vault: "path/to/my/vault",
+    copy: true, // copy the vault before installing plugins and opening in Obsidian
+    plugins: [
+        "path/to/my/plugin", // install a local plugin
+        {id: "dataview"}, // install a community plugin
+    ],
+})
+```
+This will download and launch Obsidian 1.7.7 with a sandboxed configuration directory so you don't need to worry about
+it interfering with your system Obsidian installation.
+
+## API Docs
+API docs for the package are available [here](https://jesse-r-s-hines.github.io/wdio-obsidian-service/modules/obsidian-launcher.html).
+
+
+## CLI
+`obsidian-launcher` also provides a CLI interface which can be used via `npx`
+```bash
+npx obsidian-launcher [subcommand] ...
+```
+
+Available commands:
+
+### download
+Download Obsidian to the cache without launching.
+
+```text
+Options:
+  -c, --cache <cache>        Directory to use as the download cache
+  -v, --version <version>    Obsidian version to run
+                             (default: "latest")
+  -i, --installer <version>  Obsidian installer version to run
+                             (default: "latest")
+```
+
+### install
+Install plugins and themes into an Obsidian vault.
+
+```text
+Arguments:
+  vault                  Vault to install into
+
+Options:
+  -c, --cache <cache>    Directory to use as the download cache
+  -p, --plugin <plugin>  Plugin to install. Format one of:
+                           - "<path>"
+                           - "repo:<github-repo>"
+                           - "id:<community-id>"
+                         Can be repeated.
+  -t, --theme <plugin>   Theme to install. Format one of:
+                           - "<path>"
+                           - "repo:<github-repo>"
+                           - "name:<community-name>".
+                         Can be repeated but only last will be enabled.
+```
+
+### launch
+Download and launch Obsidian, opening the specified vault. The Obsidian instance will have a sandboxed configuration
+directory.
+
+You can use this option to easily compare plugin behavior on different versions of Obsidian without messing with your
+system installation of Obsidian.
+
+```text
+Arguments:
+  vault                      Vault to open
+
+Options:
+  -c, --cache <cache>        Directory to use as the download cache
+  -v, --version <version>    Obsidian version to run
+                             (default: "latest")
+  -i, --installer <version>  Obsidian installer version to run
+                             (default: "latest")
+  -p, --plugin <plugin>      Plugin to install. Format one of:
+                               - "<path>"
+                               - "repo:<github-repo>"
+                               - "id:<community-id>".
+                             Can be repeated.
+  -t, --theme <plugin>       Theme to install. Format one of:
+                               - "<path>"
+                               - "repo:<github-repo>"
+                               - "name:<community-name>".
+                             Can be repeated but only last will be enabled.
+  --copy                     Copy the vault first
+```
+
+### watch
+Downloads Obsidian and opens a vault, then watches for changes to plugins and themes.
+
+Takes the same arguments as the `launch` command but watches for changes to any local plugins or themes and updates the
+the vault. Automatically installs `pjeby/hot-reload` so plugins will hot reload as they are updated.
+
+```text
+Arguments:
+  vault                      Vault to open
+
+Options:
+  -c, --cache <cache>        Directory to use as the download cache
+  -v, --version <version>    Obsidian version to run
+                             (default: "latest")
+  -i, --installer <version>  Obsidian installer version to run
+                             (default: "latest")
+  -p, --plugin <plugin>      Plugin to install. Format one of:
+                               - "<path>"
+                               - "repo:<github-repo>"
+                               - "id:<community-id>".
+                             Can be repeated.
+  -t, --theme <plugin>       Theme to install. Format one of:
+                               - "<path>"
+                               - "repo:<github-repo>"
+                               - "name:<community-name>".
+                             Can be repeated but only last will be enabled
+  --copy                     Copy the vault first
+```

package/dist/{chunk-E67WPRVZ.cjs → chunk-D3Z4H7XZ.cjs}

@@ -423,10 +423,11 @@ function normalizeObsidianVersionInfo(versionInfo) {
 var ObsidianLauncher = class {
   /**
    * Construct an ObsidianLauncher.
-   * @param cacheDir Path to the cache directory. Defaults to "OBSIDIAN_CACHE" env var or ".obsidian-cache".
-   * @param versionsUrl Custom `obsidian-versions.json` url. Can be a file URL.
-   * @param communityPluginsUrl Custom `community-plugins.json` url. Can be a file URL.
-   * @param communityThemes Custom `community-css-themes.json` url. Can be a file URL.
+   * @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.
    */
   constructor(options = {}) {
     this.cacheDir = _path2.default.resolve(_nullishCoalesce(_nullishCoalesce(options.cacheDir, () => ( process.env.OBSIDIAN_CACHE)), () => ( "./.obsidian-cache")));
@@ -436,18 +437,19 @@ var ObsidianLauncher = class {
     this.communityPluginsUrl = _nullishCoalesce(options.communityPluginsUrl, () => ( defaultCommunityPluginsUrl));
     const defaultCommunityThemesUrl = "https://raw.githubusercontent.com/obsidianmd/obsidian-releases/HEAD/community-css-themes.json";
     this.communityThemesUrl = _nullishCoalesce(options.communityThemesUrl, () => ( defaultCommunityThemesUrl));
+    this.cacheDuration = _nullishCoalesce(options.cacheDuration, () => ( 30 * 60 * 1e3));
     this.metadataCache = {};
   }
   /**
    * Returns file content fetched from url as JSON. Caches content to dest and uses that cache if its more recent than
    * cacheDuration ms or if there are network errors.
    */
-  async cachedFetch(url, dest, { cacheDuration = 30 * 60 * 1e3 } = {}) {
+  async cachedFetch(url, dest) {
     dest = _path2.default.resolve(dest);
     if (!(dest in this.metadataCache)) {
       let fileContent;
       const mtime = await fileExists(dest) ? (await _promises2.default.stat(dest)).mtime : void 0;
-      if (mtime && (/* @__PURE__ */ new Date()).getTime() - mtime.getTime() < cacheDuration) {
+      if (mtime && (/* @__PURE__ */ new Date()).getTime() - mtime.getTime() < this.cacheDuration) {
         fileContent = await _promises2.default.readFile(dest, "utf-8");
       } else {
         const request = await maybe(fetchWithFileUrl(url));
@@ -470,6 +472,9 @@ var ObsidianLauncher = class {
     }
     return this.metadataCache[dest];
   }
+  /**
+   * Get parsed content of the current project's manifest.json
+   */
   async getRootManifest() {
     if (!("manifest.json" in this.metadataCache)) {
       const root = _path2.default.parse(process.cwd()).root;
@@ -486,27 +491,36 @@ var ObsidianLauncher = class {
     }
     return this.metadataCache["manifest.json"];
   }
-  /** Get information about all available Obsidian versions. */
+  /**
+   * Get information about all available Obsidian versions.
+   */
   async getVersions() {
     const dest = _path2.default.join(this.cacheDir, "obsidian-versions.json");
     return (await this.cachedFetch(this.versionsUrl, dest)).versions;
   }
-  /** Get information about all available community plugins. */
+  /**
+   * Get information about all available community plugins.
+   */
   async getCommunityPlugins() {
     const dest = _path2.default.join(this.cacheDir, "obsidian-community-plugins.json");
     return await this.cachedFetch(this.communityPluginsUrl, dest);
   }
-  /** Get information about all available community themes. */
+  /**
+   * Get information about all available community themes.
+   */
   async getCommunityThemes() {
     const dest = _path2.default.join(this.cacheDir, "obsidian-community-css-themes.json");
     return await this.cachedFetch(this.communityThemesUrl, dest);
   }
   /**
    * Resolves Obsidian app and installer version strings to absolute versions.
-   * @param appVersion Obsidian version string or "latest", "latest-beta" or "earliest". "earliest" will use the 
-   *     minAppVersion set in your manifest.json.
-   * @param installerVersion Obsidian version string or "latest" or "earliest". "earliest" will use the minimum
-   *     installer version compatible with the appVersion.
+   * @param appVersion Obsidian version string 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 set in your `manifest.json`
+   * @param installerVersion Obsidian version string or one of 
+   *   - "latest": Get the latest Obsidian installer
+   *   - "earliest": Get the oldest Obsidian installer compatible with the specified Obsidian app version
    * @returns [appVersion, installerVersion] with any "latest" etc. resolved to specific versions.
    */
   async resolveVersions(appVersion, installerVersion = "latest") {
@@ -535,32 +549,31 @@ var ObsidianLauncher = class {
   }
   /**
    * Gets details about an Obsidian version.
-   * @param version Obsidian version string or "latest", "earliest", or "latest-beta". "earliest" will use the 
-   *     minAppVersion set in your manifest.json.
+   * @param appVersion Obsidian app version (see {@link resolveVersions} for format)
    */
-  async getVersionInfo(version) {
+  async getVersionInfo(appVersion) {
     const versions = await this.getVersions();
-    if (version == "latest-beta") {
-      version = versions.at(-1).version;
-    } else if (version == "latest") {
-      version = versions.filter((v) => !v.isBeta).at(-1).version;
-    } else if (version == "earliest") {
-      version = await _asyncOptionalChain([(await this.getRootManifest()), 'optionalAccess', async _27 => _27.minAppVersion]);
-      if (!version) {
-        throw Error('Unable to resolve Obsidian app version "earliest", no manifest.json or minAppVersion found.');
+    if (appVersion == "latest-beta") {
+      appVersion = versions.at(-1).version;
+    } else if (appVersion == "latest") {
+      appVersion = versions.filter((v) => !v.isBeta).at(-1).version;
+    } else if (appVersion == "earliest") {
+      appVersion = await _asyncOptionalChain([(await this.getRootManifest()), 'optionalAccess', async _27 => _27.minAppVersion]);
+      if (!appVersion) {
+        throw Error('Unable to resolve Obsidian app appVersion "earliest", no manifest.json or minAppVersion found.');
       }
     } else {
-      version = _nullishCoalesce(_semver2.default.valid(version), () => ( version));
+      appVersion = _nullishCoalesce(_semver2.default.valid(appVersion), () => ( appVersion));
     }
-    const versionInfo = versions.find((v) => v.version == version);
+    const versionInfo = versions.find((v) => v.version == appVersion);
     if (!versionInfo) {
-      throw Error(`No Obsidian app version ${version} found`);
+      throw Error(`No Obsidian app version ${appVersion} found`);
     }
     return versionInfo;
   }
   /**
    * Downloads the Obsidian installer for the given version and platform. Returns the file path.
-   * @param installerVersion Version to download.
+   * @param installerVersion Obsidian installer version to download. (see {@link resolveVersions} for format)
    */
   async downloadInstaller(installerVersion) {
     const installerVersionInfo = await this.getVersionInfo(installerVersion);
@@ -640,7 +653,11 @@ var ObsidianLauncher = class {
   }
   /**
    * Downloads the Obsidian asar for the given version and platform. Returns the file path.
-   * @param appVersion Version to download.
+   * 
+   * 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.
+   * 
+   * @param appVersion Obsidian version to download (see {@link resolveVersions} for format)
    */
   async downloadApp(appVersion) {
     const appVersionInfo = await this.getVersionInfo(appVersion);
@@ -669,10 +686,11 @@ var ObsidianLauncher = class {
    * 
    * wdio will download chromedriver from the Chrome for Testing API automatically (see
    * https://github.com/GoogleChromeLabs/chrome-for-testing#json-api-endpoints). However, Google has only put
-   * chromedriver since v115.0.5763.0 in that API, so wdio can't download older versions of chromedriver. As of
-   * Obsidian v1.7.7, minInstallerVersion is v0.14.5 which runs on chromium v100.0.4896.75. Here we download
-   * chromedriver for older versions ourselves using the @electron/get package which fetches it from
-   * https://github.com/electron/electron/releases.
+   * chromedriver since v115.0.5763.0 in that API, so wdio can't automatically download older versions of chromedriver
+   * for old Electron versions. Here we download chromedriver for older versions ourselves using the @electron/get
+   * package which fetches chromedriver from https://github.com/electron/electron/releases.
+   * 
+   * @param installerVersion Obsidian installer version (see {@link resolveVersions} for format)
    */
   async downloadChromedriver(installerVersion) {
     const versionInfo = await this.getVersionInfo(installerVersion);
@@ -761,11 +779,13 @@ var ObsidianLauncher = class {
     return await this.downloadGitHubPlugin(pluginInfo.repo, version);
   }
   /**
-   * Downloads a list of plugins to the cache and returns a list of LocalPluginEntry with the downloaded paths.
+   * 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.
    * 
    * You can download plugins from GitHub using `{repo: "org/repo"}` and community plugins using `{id: 'plugin-id'}`.
    * Local plugins will just be passed through.
+   * 
+   * @param plugins List of plugins to download.
    */
   async downloadPlugins(plugins) {
     return await Promise.all(
@@ -802,7 +822,12 @@ var ObsidianLauncher = class {
             throw Error(`${pluginPath}/manifest.json malformed.`);
           }
         }
-        const enabled = typeof plugin == "string" ? true : plugin.enabled;
+        let enabled;
+        if (typeof plugin == "string") {
+          enabled = true;
+        } else {
+          enabled = _nullishCoalesce(plugin.enabled, () => ( true));
+        }
         return { path: pluginPath, id: pluginId, enabled, originalType };
       })
     );
@@ -858,11 +883,13 @@ var ObsidianLauncher = class {
     return await this.downloadGitHubTheme(themeInfo.repo);
   }
   /**
-   * Downloads a list of themes to the cache and returns a list of LocalThemeEntry with the downloaded paths.
+   * 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.
    * 
    * You can download themes from GitHub using `{repo: "org/repo"}` and community themes using `{name: 'theme-name'}`.
    * Local themes will just be passed through.
+   * 
+   * @param themes List of themes to download
    */
   async downloadThemes(themes) {
     return await Promise.all(
@@ -900,15 +927,20 @@ var ObsidianLauncher = class {
             throw Error(`${themePath}/manifest.json malformed.`);
           }
         }
-        const enabled = typeof theme == "string" ? true : theme.enabled;
+        let enabled;
+        if (typeof theme == "string") {
+          enabled = true;
+        } else {
+          enabled = _nullishCoalesce(theme.enabled, () => ( true));
+        }
         return { path: themePath, name: themeName, enabled, originalType };
       })
     );
   }
   /**
-   * Installs plugins into an Obsidian vault.
-   * @param vault Path to the vault to install the plugin in.
-   * @param plugins List plugins paths to install.
+   * Installs plugins into an Obsidian vault
+   * @param vault Path to the vault to install the plugins in
+   * @param plugins List plugins to install
    */
   async installPlugins(vault, plugins) {
     const downloadedPlugins = await this.downloadPlugins(plugins);
@@ -958,9 +990,9 @@ var ObsidianLauncher = class {
     }
   }
   /** 
-   * Installs themes into an obsidian vault.
-   * @param vault Path to the theme to install the plugin in.
-   * @param themes: List of themes to install.
+   * Installs themes into an Obsidian vault
+   * @param vault Path to the theme to install the themes in
+   * @param themes List of themes to install
    */
   async installThemes(vault, themes) {
     const downloadedThemes = await this.downloadThemes(themes);
@@ -998,13 +1030,13 @@ var ObsidianLauncher = class {
     }
   }
   /**
-   * Sets up the config dir to use for the --user-data-dir in obsidian. Returns the path to the created config dir.
+   * Sets up the config dir to use for the `--user-data-dir` in obsidian. Returns the path to the created config dir.
    *
-   * @param appVersion Obsidian version string.
-   * @param installerVersion Obsidian version string.
-   * @param appPath Path to the asar file to install. Will download if omitted.
-   * @param vault Path to the vault to open in Obsidian.
-   * @param dest Destination path for the config dir. If omitted it will create it under `/tmp`.
+   * @param params.appVersion Obsidian app version (see {@link resolveVersions} for format)
+   * @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.
    */
   async setupConfigDir(params) {
     const [appVersion, installerVersion] = await this.resolveVersions(params.appVersion, params.installerVersion);
@@ -1018,6 +1050,9 @@ var ObsidianLauncher = class {
       // prevents the changelog page on boot
     };
     if (params.vault !== void 0) {
+      if (!await fileExists(params.vault)) {
+        throw Error(`Vault path ${params.vault} doesn't exist.`);
+      }
       const vaultId = _crypto2.default.randomBytes(8).toString("hex");
       obsidianJson = {
         ...obsidianJson,
@@ -1049,17 +1084,17 @@ var ObsidianLauncher = class {
   /**
    * Sets up a vault for Obsidian, installing plugins and themes and optionally copying the vault to a temporary
    * directory first.
-   * @param vault Path to the vault to open in Obsidian.
-   * @param copy Whether to copy the vault to a tmpdir first. Default false.
-   * @param plugins List of plugins to install in the vault.
-   * @param themes List of themes to install in the vault.
+   * @param params.vault Path to the vault to open in Obsidian
+   * @param params.copy Whether to copy the vault to a tmpdir first. Default false
+   * @param params.plugins List of plugins to install in the vault
+   * @param params.themes List of themes to install in the vault
    * @returns Path to the copied vault (or just the path to the vault if copy is false)
    */
   async setupVault(params) {
     let vault = params.vault;
     if (params.copy) {
       const dest = await makeTmpDir("obs-launcher-vault-");
-      await _promises2.default.cp(vault, dest, { recursive: true });
+      await _promises2.default.cp(vault, dest, { recursive: true, preserveTimestamps: true });
       vault = dest;
     }
     await this.installPlugins(vault, _nullishCoalesce(params.plugins, () => ( [])));
@@ -1070,20 +1105,24 @@ var ObsidianLauncher = class {
    * 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.
+   * This is just a shortcut for calling `downloadApp`, `downloadInstaller`, `setupVault` and `setupConfDir`.
    *
-   * @param appVersion Obsidian version string.
-   * @param installerVersion Obsidian version string.
-   * @param vault Path to the vault to open in Obsidian.
-   * @param copy Whether to copy the vault to a tmpdir first. Default false.
-   * @param plugins List of plugins to install in the vault.
-   * @param themes List of themes to install in the vault.
-   * @param args CLI args to pass to Obsidian
-   * @param spawnOptions Options to pass to `spawn`.
-   * @returns The launched child process and the created tmpdirs.
+   * @param params.appVersion Obsidian app version (see {@link resolveVersions} for format). Default "latest"
+   * @param params.installerVersion Obsidian installer version (see {@link resolveVersions} for format).
+   *   Default "latest"
+   * @param params.vault Path to the vault to open in Obsidian
+   * @param params.copy Whether to copy the vault to a tmpdir first. Default false
+   * @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.spawnOptions Options to pass to `spawn`
+   * @returns The launched child process and the created tmpdirs
    */
   async launch(params) {
-    const [appVersion, installerVersion] = await this.resolveVersions(params.appVersion, params.installerVersion);
+    const [appVersion, installerVersion] = await this.resolveVersions(
+      _nullishCoalesce(params.appVersion, () => ( "latest")),
+      _nullishCoalesce(params.installerVersion, () => ( "latest"))
+    );
     const appPath = await this.downloadApp(appVersion);
     const installerPath = await this.downloadInstaller(installerVersion);
     let vault = params.vault;
@@ -1197,6 +1236,8 @@ var ObsidianLauncher = class {
   }
   /**
    * Returns true if the Obsidian version is already in the cache.
+   * @param type on of "app" or "installer"
+   * @param version Obsidian app/installer version (see {@link resolveVersions} for format)
    */
   async isInCache(type, version) {
     version = (await this.getVersionInfo(version)).version;
@@ -1210,8 +1251,9 @@ var ObsidianLauncher = class {
     return await fileExists(_path2.default.join(this.cacheDir, dest));
   }
   /**
-   * Returns true if we either have the credentails to download the version or it's already in cache.
+   * Returns true if we either have the credentials to download the version or it's already in cache.
    * This is only relevant for Obsidian beta versions, as they require Obsidian insider credentials to download.
+   * @param version Obsidian version (see {@link resolveVersions} for format)
    */
   async isAvailable(version) {
     const versionInfo = await this.getVersionInfo(version);
@@ -1229,4 +1271,4 @@ var ObsidianLauncher = class {
 
 
 exports.ObsidianLauncher = ObsidianLauncher;
-//# sourceMappingURL=chunk-E67WPRVZ.cjs.map
+//# sourceMappingURL=chunk-D3Z4H7XZ.cjs.map