@todesktop/cli 1.18.2 → 1.19.0-0

package/README.md

@@ -12,6 +12,7 @@ For more information, visit the project
 - [Get started](#get-started)
 - [CLI commands](#cli-commands)
 - [Release Webhooks](#release-webhooks)
+- [Introspection & breakpoints](#introspection--breakpoints)
 - [Automating your builds (CI)](#automating-your-builds-ci)
 - [Project configuration (todesktop.json, todesktop.js, or todesktop.ts)](#project-configuration-todesktopjson-todesktopjs-or-todesktops)
 - [Build lifecycle hooks (package.json scripts)](#build-lifecycle-hooks-packagejson-scripts)
@@ -47,7 +48,7 @@ Create a `todesktop.json` file in the root of your Electron project.
 
 ```json
 {
-  "$schema": "https://unpkg.com/@todesktop/cli@1.18.2/schemas/schema.json",
+  "$schema": "https://unpkg.com/@todesktop/cli@1.19.0/schemas/schema.json",
   "schemaVersion": 1
   "id": "your-todesktop-id",
   "icon": "./desktop-icon.png",
@@ -194,6 +195,17 @@ We also support:
   flag.
 - `todesktop build --ignore-extends-errors`. Ignore `id` and `appId` validation
   errors when extending another configuration file (`.json` or `.js`).
+- `todesktop build --introspect`. Run a build with an active introspection
+  tunnel so you can inspect the build agent while it runs.
+- `todesktop build --breakpoints=<comma-separated-list>`. Requires
+  `--introspect`; accepts phase names (for example `beforeInstall`) and hook
+  forms such as `hook:todesktop:beforeInstall:after`. Aliases and wildcards like
+  `hook:todesktop:beforeInstall:*` are expanded automatically and the resolved
+  queue is printed before the build starts.
+- `todesktop build --breakpoints=list`. Print the catalog of supported
+  breakpoints with descriptions.
+- `todesktop build --continue <buildId> --platform mac|windows|linux`. Resume a
+  paused build from another terminal using the same account that initiated it.
 - `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.
@@ -206,6 +218,7 @@ We also support:
     reasons, you can only release apps through the
     [web UI](https://app.todesktop.com) with security token authentication. If
     you wish to enable CLI releases, please contact support with your app ID.
+
 - `todesktop builds`. View your recent builds.
   - Use `todesktop builds <id>` to view a specific build and its progress.
   - `todesktop builds --latest` will show the latest build and it's progress.
@@ -222,10 +235,57 @@ We also support:
   - `todesktop smoke-test --latest` will test the latest build.
   - Append `--config=<path.to.config.file>` to use a different configuration
     file.
+- `todesktop introspect [buildId]`. Connect to a running build’s shell when
+  introspection is enabled. If you omit the build ID, the CLI will prompt you to
+  pick a build and platform.
 - `todesktop whoami`. Prints the email of the account you're signed into.
 - `todesktop --help`. Shows the help documentation.
 - `todesktop --version`. Shows the current version of the CLI.
 
+## Introspection & breakpoints
+
+Interactive introspection lets you open a shell on a live build agent and pause
+the build at deterministic breakpoints for deeper debugging.
+
+### Enable introspection on a build
+
+- Run `todesktop build --introspect` to start a build with an introspection
+  tunnel. The CLI prints availability notices and keeps the session attached
+  while the build runs.
+- Add `--breakpoints=list` to print the supported pause points and their
+  descriptions.
+- Provide a comma-separated list via
+  `--breakpoints=beforeInstall,hook:todesktop:beforeInstall:after,afterPack`
+  (requires `--introspect`). Phase names such as `beforeInstall` and hook forms
+  like `hook:todesktop:beforeInstall:before` are validated, deduplicated, and
+  expanded to cover aliases (for example `hook:todesktop:beforeInstall:*`
+  expands to both before/after hook breakpoints).
+
+### Working with paused builds
+
+- When a breakpoint is hit, the CLI displays a prompt similar to
+  `mac paused at beforeInstall (lease expires in 20m)`.
+- Use `Enter` to resume to the next breakpoint, `x` to skip the remaining
+  breakpoints, `space` to renew the lease (adds 10 minutes when less than 20
+  minutes remain), and `Ctrl+C` to detach without resuming.
+- The default lease lasts 20 minutes; inactivity triggers an automatic resume
+  which is surfaced as `autoResumed` in the CLI output and Firestore metadata.
+- Only collaborators on the same app account can renew, resume, or skip
+  breakpoints; requests from other accounts return a permission error.
+
+### Control a paused build from another terminal
+
+- Run `todesktop build --continue <buildId> --platform mac|windows|linux` to
+  resume a paused platform. This mirrors pressing `Enter` in the interactive
+  prompt and requires that the target platform is currently paused.
+
+### Open an introspection shell
+
+- Run `todesktop introspect [buildId]` to connect to the build agent shell. If
+  you omit the build ID, the CLI presents a list of running builds with
+  introspection enabled followed by a platform picker that shows each platform’s
+  breakpoint and shell status (for example `⏸ mac (paused)`).
+
 ## Automating your builds (CI)
 
 You may want to automate builds with your Continuous Integration (CI) provider.
@@ -319,7 +379,7 @@ To enable JSON validation and IntelliSense for your `todesktop.json` file in com
 - For example, if using a hosted version of the schema:
   ```json
   {
-    "$schema": "https://unpkg.com/@todesktop/cli@1.18.2/schemas/schema.json",
+    "$schema": "https://unpkg.com/@todesktop/cli@1.19.0/schemas/schema.json",
     "id": "your-todesktop-id"
   }
   ```
@@ -1531,6 +1591,20 @@ Now, when we build your app on ToDesktop servers, it will also run your custom
 
 ## Changelog
 
+### 1.19.0
+
+#### Minor Changes
+
+- dc5fe40: Add `todesktop build --introspect` flag and
+  `todesktop introspect [buildId]` command for interactive shell access to
+  in-progress builds
+
+### 1.18.3
+
+#### Patch Changes
+
+- 51821cc: Add support for pnpm workspace catalogs in workspace bundling
+
 ### 1.18.2
 
 #### Patch Changes