@stim-cli/server 1.21.0 → 1.23.0

package/README.md

@@ -152,6 +152,100 @@ limits and the report execution/cleanup budgets apply. Disconnect or shutdown
 cancels the request and drains its owned work. Cached doctor report reads do not
 record checks.
 
+The local-only `desktop-run` feature provides `desktop.run.subscribe` with an
+absolute `cwd` and `options` matching the typed `stim.run` selectors. For example,
+`{ "cwd": "/absolute/app", "options": { "platform": "ios", "slot": "fold", "remote": "mini" } }`
+builds, installs and launches through the in-process API. Only a proved private
+Desktop session can call it; adopted servers and local control alone cannot.
+`desktop-run-progress` carries ordered `stream`/`message` chunks, followed by
+`desktop-run-ended` with `exitCode`, a human `message`, and `stdout` containing
+the serialized `{ platform, facts }` API result or typed refusal. The default
+execution budget is one hour; progress plus the terminal JSON are limited to
+1 MiB. Cancellation, unsubscribe, disconnect and server shutdown cancel and drain
+owned work before releasing workspace admission. Unresolved cleanup retains the
+reservation until every recorded claim is recovered. If cleanup cannot name its
+claims, admission stays blocked until the server restarts; recover the owned work
+before restarting. Reconnect never replays a run. Desktop's platform buttons
+still use the CLI until their consumer migration.
+
+The private `desktop-build` feature provides `desktop.build.subscribe` with an
+absolute `cwd` and artifact-only `options`: `ios` accepts `configuration`, `scheme`
+and `arch`; `android` accepts `variant` and `abi`; both accept `buildCache` and
+`remoteBuild`. `macos` accepts `remoteBuild`. It invokes `createStim.build`
+without acquiring a device or starting a runtime. Device, slot, hosted-launch,
+Metro and EAS selectors are refused. It uses the same proved Desktop authority,
+one-hour default budget, 1 MiB output bound and cleanup admission as platform
+run. Ordered `desktop-build-progress` events end with `desktop-build-ended`,
+whose `stdout` contains `{ platform, facts }` or the typed refusal. Reconnecting
+never replays a build. This transport is a migration prerequisite; existing
+Desktop buttons do not use it yet.
+
+The private `desktop-gc` feature provides `desktop.gc.subscribe` with an absolute
+existing `cwd` and optional `cache`, `olderThan` (whole days), `worktrees`, `delete`
+and `idleMs` (positive whole milliseconds). It invokes `createStim.collectGarbage`
+with the same scoped cleanup and ownership rules as the CLI. Only the proved
+Desktop connection can call it; phone, network and adopted-server connections
+cannot. Ordered `desktop-gc-progress` events end with `desktop-gc-ended`, whose
+`stdout` contains the GC JSON report or typed refusal and whose `exitCode` preserves
+partial cleanup failures. It preserves the API's 60-second execution and 35-second
+cleanup budgets. The server's request deadline can cancel execution earlier; its
+progress plus terminal JSON bound is 1 MiB. Unsubscribe, disconnect, shutdown and timeout
+cancel and drain owned work before releasing admission; unresolved cleanup retains
+the reservation and its recovery claims. Settled requests invalidate cached Desktop
+reports. Reconnect never repeats cleanup. Desktop GC buttons still use the CLI
+until their consumer migration.
+
+The private `desktop-worktree-remove` feature provides
+`desktop.worktree.remove.subscribe` with an absolute existing `cwd`, an optional
+absolute `target`, and optional boolean `force`. It calls `createStim.removeWorktree`
+with the CLI's safety checks and ownership rules. A separate target can be absent
+on disk when retrying pending branch cleanup. Only the proved connection of the
+Desktop that started this server can call it; paired phones and adopted local
+connections cannot.
+
+Ordered `desktop-worktree-remove-progress` events end with
+`desktop-worktree-remove-ended`. Its `stdout` contains `{ removed, exitCode }` or
+a typed refusal. Admission covers the resolved checkout or project and every
+registered descendant reclaimed by cleanup, including when the request names a
+subfolder. Deletion and cleanup success remain separate: source cleanup
+can succeed without deleting a checkout, and branch cleanup can fail after a
+linked checkout was deleted. `force` has the CLI's destructive meaning. The API's
+60-second execution and 35-second cleanup budgets and the server's deadline and
+output limit apply. Cancellation drains owned work before releasing admission;
+unresolved cleanup retains its recovery claims. Settled requests invalidate
+cached Desktop reports. Reconnect never repeats removal. Desktop callers migrate
+separately.
+
+The private `desktop-worktree-warm` feature provides
+`desktop.worktree.warm.subscribe` with only an absolute existing `cwd`. It calls
+`createStim.warmWorktree` for plain copying; refresh and dependency installation
+remain CLI-only. Only the proved connection of the Desktop that started this
+server can call it. Phones, network clients and adopted local connections cannot.
+
+Ordered `desktop-worktree-warm-progress` events end with
+`desktop-worktree-warm-ended`, whose `stdout` contains `{ exitCode }` or a typed
+refusal. The default request budget is 90 minutes, with an explicitly configured
+server action deadline taking precedence. The API's 35-second cleanup budget and
+the server's 1 MiB progress-plus-result bound apply. Admission covers the resolved
+linked checkout, its registered descendants and the inferred app before effects.
+Cancellation drains owned work before releasing admission; unverifiable cleanup
+retains admission until its exact recovery claims are cleared. Settled requests
+invalidate cached Desktop reports. Reconnect never repeats warming. Desktop
+callers migrate separately.
+
+The private `desktop-plan` feature provides `desktop.plan.get` with an absolute
+existing `cwd`, `platform` (`ios`, `android` or `macos`) and an optional iOS/Android
+`slot`. An optional `request` identifies that connection's check. It returns the shared `createStim.plan` report or a typed `{ code, message, remedy }` refusal without a CLI process,
+building or launching. Only the proved Desktop connection can select folders;
+phones and ordinary local connections cannot use it. The existing `build.plan`
+method remains limited to registered iOS/Android workspaces. Both paths share
+per-directory queues, connection request limits, output bounds and cancellation.
+The planner has a 60-second execution and 35-second cleanup budget inside the
+server's 150-second request deadline, which starts after queued work drains.
+These bounded plans support EAS and Stim cache providers; legacy custom Expo
+cache plugins are checked only by CLI plans.
+Desktop preview consumers use this private read. `desktop.plan.cancel { request }` cancels only a check on the same proved connection and replies after its queued work and cleanup drain. A retained cleanup failure is included as `refusal` in the cancellation result; other connections cannot cancel it. Shared subscriptions stay connected.
+
 The local-only `desktop-stop` feature provides `desktop.stop.subscribe` with an
 absolute `cwd` and optional `slot` (`web` closes only the owned Chrome). It stops
 that exact canonical workspace through the shared API, without searching for a
@@ -1191,11 +1285,17 @@ systems refuse; start stim-server from your own service manager there:
 stim-server service install [--port <n>] [--label <name>] [--serve]
                             [--env KEY=VALUE]... [--path-prepend <dir>]...
 stim-server service status [--label <name>] [--json]
-stim-server service update [--label <name>] --release <version>|--from <dir>
+stim-server service update [--label <name>] [--no-wait] --release <version>|--from <dir>
 stim-server service rollback [--label <name>]
 stim-server service uninstall [--label <name>]
 ```
 
+Updates wait for offloaded builds and hosted sessions to finish by default.
+Use `--no-wait` to restart with work still active: shutdown interrupts those
+builds and sessions. Service shutdown, health checks and rollback still apply.
+`stim-server setup --no-wait` uses the same policy when it updates a managed
+service; if setup requires a separate service update, its remedy includes the flag.
+
 `install` writes `~/Library/LaunchAgents/<label>.plist` (label `dev.stim.server`
 by default) and starts it with `launchctl bootstrap gui/<uid>`. The job starts
 Stim Host, which stays alive as the parent of the absolute `node` and
@@ -1508,9 +1608,13 @@ connected since stim-server started keeps its directory when revoked.
   the JDK in `JAVA_HOME` or the macOS default; and `androidSdk`, the `ndk`,
   `buildTools` and `platforms` directories of the SDK in `ANDROID_HOME`, else `~/Library/Android/sdk` on macOS or
   `~/Android/Sdk` on Linux, null without one), `capacity` and `warm`
-  (`checkout`, `dependencies` when the last install used that lockfile, and
-  `build` once a build ran there, including a non-empty repository `macos/`
-  scratch directory) for that repository. `capacity` holds
+  (`checkout`, `dependencies`, and the legacy `build` field, now always false)
+  for that repository. For React Native and Expo builds, clients supporting `build-dependency-cache` can send
+  `dependencies: { project, packageName }` alongside `lockfile`; the dependency
+  hint requires the selected project's installed modules and a matching install
+  marker, including the package-manager arguments. Without that query it is
+  false. Clients ignore older workers' unverified warmth and do not rank
+  checkout or build-directory presence as cache state. `capacity` holds
   `running` and `max` offloaded builds, `diskFreeBytes` of the worker root's
   volume and `minDiskFreeBytes`, `cpus`, `loadPerCore` (the 5-minute load
   average per CPU), `builds` (this machine's own Stim runs in prebuild, pods or
@@ -1532,6 +1636,31 @@ connected since stim-server started keeps its directory when revoked.
   or `{ fingerprint, cacheKey, name, size, sha256 }` for a completed archive in
   this client's repository area. The key includes source, toolchain, SDK,
   architecture and target options. These are exact lookups, not a full inventory.
+  With `react-native-peer-cache`, a React Native/Expo development offer can send
+  `reactNativeArtifact: { project, fingerprint, isExpo, platform, toolchain, ios | android }`.
+  The query includes the caller's compatible toolchain and normalized native
+  build choices; the worker constructs its own receipt around compilation.
+  The returned identity is opaque, not an alias for the caller's local cache key.
+  The completed receipt binds the worker-verified post-mutation fingerprint
+  and native options to the toolchain checked before and after compilation.
+  Lookup uses that immutable receipt, so a later checkout or toolchain change
+  does not discard a matching archive. Older workers receive no new query
+  parameters and continue through their normal build path.
+  With `swiftpm-peer-cache`, `swiftpmArtifact` carries `project`, `sourceDigest`,
+  `stimBuild`, complete `inputs` (`ignored`, `outputs`, `localFiles`,
+  `environment`) and `build` (`product`, `infoPlist`, `resources`, `assetCatalog`).
+  Resource and catalog paths are repository-relative; the plist is
+  project-relative. The worker verifies actual transferred files and full
+  artifact identity around compilation, then retains an opaque receipt.
+  Private input values stay on that worker and are rechecked on every lookup.
+  SDKROOT, then SWIFTPM_SDKROOT_macosx, selects the SDK ahead of the default;
+  its real path and build version are revalidated.
+  A matching archive survives checkout and job-output pruning when those
+  private inputs remain available and unchanged and its direct Apple toolchain
+  selection can be reproduced. Command paths and versions are checked from the
+  package directory, including SWIFT_EXEC and SWIFT_EXEC_MANIFEST compiler overrides.
+  Overrides and custom Swift, xcrun or xcodebuild launchers require the
+  checkout and become a miss after it is removed.
 - `build.cached-artifact` takes `repo` and `artifact: { fingerprint, cacheKey }`.
   It requires the existing build approval. It verifies and streams the cached
   archive with the same digest-prefixed binary frames as `build.artifact`, and
@@ -1540,6 +1669,13 @@ connected since stim-server started keeps its directory when revoked.
   worker archives survive job-output cleanup in their client's repository cache;
   removing that client's worker area removes the cache too. Other clients and
   repositories cannot look up those entries.
+  React Native archives also require the same `reactNativeArtifact` query on
+  download, checked against the completed receipt again. An identity alone
+  cannot fetch them. Archives use the existing complete-file cache and digest verification;
+  a hit uploads no source and takes no compiler slot. A missing or corrupt
+  archive falls back through the caller's existing placement policy.
+  SwiftPM archives require the same `swiftpmArtifact` query on fetch and another
+  private-input check; their opaque keys alone cannot fetch an archive.
 - `build.sync` takes `repo`, `files` and `done`. `files` is one page of the
   manifest, each `{ "path", "kind": "file"|"exec"|"link", "size", "sha256" }`,
   a link's blob being its target. Pages accumulate until `done`; the next
@@ -1562,7 +1698,9 @@ connected since stim-server started keeps its directory when revoked.
   `fingerprint`, `packageName`, `isExpo`, `optimizations`, `android` (for
   `android`: `variant`, `abi`, `gradleBuildCache`, `pch` and `compilerCache`,
   `ccache` or `none`) and `stimBuild`, after the whole manifest of `repo` was
-  synced on this connection. It returns `{ "job" }`. It fails with
+  synced on this connection. A peer-cache-capable React Native caller can set
+  `cacheArtifact: true` to retain a completed development archive when its cache
+  write and remote policies allow it. It returns `{ "job" }`. It fails with
   `build-busy` while the offer would be declined, naming the reason, or while
   another build of the same client and repository runs, or while every one
   of this machine's `concurrency.maxBuilds` slots is held, and with
@@ -1619,7 +1757,11 @@ connected since stim-server started keeps its directory when revoked.
   It returns that app as a tar archive, its manifest fingerprint, timings and
   `compilationCache: {}`. The client verifies the digest, identity, executable
   and signature before promotion and launches locally. Every offload failure
-  falls back locally; macOS artifacts are not cached. Matching Xcode and macOS
+  falls back locally. A caller with remote artifact caching enabled can set
+  `cacheArtifact: true` and `macos.artifactInputs` for declared repeatable,
+  relocatable apps. Completed archive retention requires matching worker
+  input identities before and after the build; ignored bundle files need
+  explicit private declarations. Matching Xcode and macOS
   SDK are required, and the worker needs network access for the first SwiftPM
   dependency fetch; the dependency cache is shared only within that client.
 - `build.progress` events `{ "event": "build.progress", "job", ... }` carry a
@@ -2070,13 +2212,13 @@ Events are `{ "event", "subscription", ... }`.
   deleted.
 - `build.plan` takes `workspace`, `platform` (`ios` or `android`) and `slot`
   (`default` when absent), and returns the payload of
-  `stim <platform> --plan --json` run in the workspace: the fingerprint, the
+  `stim <platform> --plan --json` through the shared in-process API: the fingerprint, the
   cache result the next build would get (`local`, `remote` or `false`), the
   prebuild decision, `expectedMs` with its `basis`, and on a predicted cold
   build its `missReason`. It builds, boots and
   installs nothing and writes no Stim state; a remote cache check can
-  download the artifact into a temporary directory, so it gets 150 seconds
-  instead of 60. A plan predicting that the build would refuse is a result
+  download the artifact into a temporary directory. The planner has a 60-second
+  execution and 35-second cleanup budget inside the 150-second request limit. A plan predicting that the build would refuse is a result
   whose `refusal` holds the code, message and remedy. A plan that cannot be
   computed is a `stim-failed` error. One plan runs per workspace at a time,
   across all connections; later requests wait their turn, and the 150
@@ -2190,8 +2332,8 @@ a time. `logs.query`, `stats.get` and `settings.get` fail after 60 seconds,
 `build.plan` after 150; these four fail at 32 MiB of output. Closing the
 connection stops running requests. When the command refuses with Stim's error
 contract on stdout, the `stim-failed` message is its code, message and remedy;
-otherwise it is the exit status and the end of stderr. A `stim` child that
-ignores SIGTERM gets SIGKILL a second later. A log subscriber whose socket has more than
+otherwise the message describes the failed read. In-process reads cancel their
+owned children and drain cleanup before releasing their request slot. A log subscriber whose socket has more than
 4 MiB unsent gets no more batches until it catches up; past 20,000
 waiting records the server ends that subscription with `slow-client`.