@todesktop/cli 1.7.7 → 1.8.1

package/README.md

@@ -135,6 +135,8 @@ We also support:
 
 - `todesktop build --code-sign=false`. Run a build with code-signing and notarization disabled. This is handy for testing builds quickly.
 - `todesktop build --config=<path.to.another.todesktop.json>`. Run a build with a different configuration file.
+- `todesktop build --async`. Run a build in the background. This is handy for CI environments.
+- `todesktop build --webhook URL`. Send a POST request to the webhook URL when the build is finished. It's especially useful together with the `--async` flag.
 - `todesktop release`. Release a build. This will publish a new download and an auto-update for existing users. By default it shows a list of builds for you to choose from.
   - Use `todesktop release <id>` to release a specific build by ID.
   - `todesktop release --latest` will release the latest build.
@@ -171,6 +173,38 @@ To build and release in one step, you can execute:
 todesktop build && todesktop release --latest --force
 ```
 
+If you need to run a build in the background, you can use the `--async` flag. To
+get notified when the build is finished you can optionally specify a webhook URL
+which will receive a POST request with the build data:
+
+```sh
+todesktop build --async --webhook https://example.com/build-finished-webhook
+```
+
+The webhook receives a POST request with the following JSON body:
+
+```
+POST https://example.com/build-finished-webhook
+{
+  appId: string;
+  accountUserEmail: string;
+  accountUserId: string;
+  artifacts: {
+    linux?: LinuxArtifactDownloads;
+    mac?: MacArtifactDownloads;
+    windows?: WindowsArtifactDownloads;
+  };
+  buildId: string;
+  endedAt: string; // 2023-01-01T00:00:00Z
+  errorMessage?: string;
+  requesterUserEmail: string;
+  requesterUserId: string; // The same as accountUserId or `contextUserId`
+  schemaVersion: number; // Currently always `1`
+  startedAt: string; // 2023-01-01T00:00:00Z
+  status:  'queued' | 'failed' | 'building' | 'preparation' | 'succeeded' | 'cancelled';
+}
+```
+
 ## Project configuration (todesktop.json)
 
 This describes all of the possible configuration options ín your `todesktop.json`.
@@ -187,7 +221,7 @@ Example: `["dist/**", "!static/**"]`
 
 This option allows you to decide which files get uploaded to be built on the ToDesktop servers. By default, all files in your app path are included in your app, except for `node_modules` and `.git`. Dependencies are installed on our build servers as there could be platform-specific postinstall steps.
 
-If you wish to include files for the build process but exclude them in the distribtion version of your app then you should use the [`filesForDistribution`](#filesForDistribution---optional-array-of-glob-patterns) property
+If you wish to include files for the build process but exclude them in the distribution version of your app then you should use the [`filesForDistribution`](#filesForDistribution---optional-array-of-glob-patterns) property
 
 The files must be within your [`appPath`](#apppath---optional-string).
 
@@ -425,9 +459,12 @@ Example:
 - `ext` String | Array<String> - The extension (minus the leading period). e.g. png.
 - `name` String - The name. e.g. PNG. Defaults to value of `ext`.
 - `description` String - windows-only. The description.
+- `icon` String - macOS and windows. Icon file name without extension. It points
+  to ico file for Windows and icns for macOS. For example, if the `icon` value is `"icons/py"` then it will look for both `"icons/py.ico"` and `"icons/py.icns"` in your project directory.
 - `mimeType` String - linux-only. The mime-type.
-- `role` = `Editor` String - macOS-only The app’s role with respect to the type. The value can be `Editor`, `Viewer`, `Shell`, or `None`. Corresponds to `CFBundleTypeRole`.
-- `isPackage` Boolean - macOS-only Whether the document is distributed as a bundle. If set to true, the bundle directory is treated as a file. Corresponds to `LSTypeIsPackage`.
+- `role` = `Editor` String - macOS-only. The app’s role with respect to the type. The value can be `Editor`, `Viewer`, `Shell`, or `None`. Corresponds to `CFBundleTypeRole`.
+- `isPackage` Boolean - macOS-only. Whether the document is distributed as a bundle. If set to true, the bundle directory is treated as a file. Corresponds to `LSTypeIsPackage`.
+- `rank` = `Default` String macOS-only. Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type. The possible values are: `Owner` (this app is the primary creator of files of this type), `Default` (this app is an opener of files of this type; this value is also used if no rank is specified), `Alternate` (this app is a secondary viewer of files of this type), and `None` (this app is never selected to open files of this type, but it accepts drops of files of this type).
 
 ### `filesForDistribution` - (optional) array of glob patterns
 
@@ -605,6 +642,12 @@ Example: `yarn`
 
 The package manager to use when installing dependencies. Valid values are `npm`, `yarn` or `pnpm`.
 
+### `pnpmVersion` - string
+
+Example: `8.10.5`.
+
+The version of pnpm that ToDesktop should use for installation.
+
 ### `schemaVersion` - number
 
 Example: `1`.
@@ -850,8 +893,8 @@ The `afterPack` function also has the following arguments added to it's signatur
 - shouldCodeSign - boolean - whether the app will be code signed or not
 - outDir - string - the path to the output directory
 - appOutDir - string - the path to the app output directory
-- arch - string - the architecture of the app
 - packager - object - the packager object
+- arch - number - the architecture of the app. `ia32 = 0`, `x64 = 1`, `armv7l = 2`, `arm64 = 3`, `universal = 4`.
 
 Example script:
 
@@ -899,6 +942,24 @@ To summarize:
 
 Note: **Do not put a token in this file**. You are specifying a literal value of `${NPM_TOKEN}`. NPM will replace the value for you. 5. Add `.npmrc` to your `appFiles` array `[".npmrc"]` in `todesktop.json`.
 
+### How can I specify a specific yarnVersion for use with my app?
+
+By default, ToDesktop uses version `1.x.x` of `Yarn` if a `yarn.lock` file is present in your project. You can override this by creating a `.yarnrc.yml` file in your project directory and specifying the `yarnPath` property to point to your specified version of yarn:
+
+```yml
+yarnPath: .yarn/releases/yarn-3.1.1.cjs
+```
+
+This can be done automatically by running `yarn set version x.x.x` from within your project directory. This will create a `.yarnrc.yml` file and a corresponding `.yarn/releases/yarn-x.x.x.cjs` that the `yarnPath` property points to. This will also add a `packageManager` field in your `package.json` with a value of `yarn@x.x.x`
+
+It's important to ensure that the `.yarn` folder is included in your build. If you had previously changed your `todesktop.json`'s [`appFiles`](#appfiles---optional-array-of-glob-patterns) property from its default glob implementation of `**`, then please ensure that it includes the `.yarn` directory:
+
+Example: `[".yarn/**", ".yarnrc.yml", "...include your other changes here..."]`
+
+You will want to exclude the `.yarn` directory in the distribution version of your app. You can use the [`filesForDistribution`](#filesForDistribution---optional-array-of-glob-patterns) property to achieve this:
+
+Example: `[".yarn/**", ".yarnrc.yml"]`
+
 ### How do I create a staging version of my app?
 
 ToDesktop CLI supports the concept of a staging version of your app. This is useful if you want to test your app before releasing it to the public. To create a staging version of your app, you need to do the following:
@@ -989,6 +1050,17 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
 
 ## Changelog
 
+### v1.8.1
+
+- Revert support for `yarnVersion` in config. Instead use `.yarnrc.yml` file to specify yarn version.
+
+### v1.8.0
+
+- Add support for `--webhook` flag for `todesktop build` command
+- Add support for `--async` flag to run a build in the in the background
+- Add support for specifying custom `yarnVersion` in config
+- Add support for specifying custom `pnpmVersion` in config
+
 ### v1.7.7
 
 - Report errors when S3 upload fails and retry 3 times