stim 1.20.2 → 1.21.0

package/README.md

@@ -44,13 +44,24 @@ Stim builds or restores the app, installs it, launches it, and checks launch
 readiness. Plain output streams progress and reports the complete result. Use
 `--json` when a script needs structured data.
 
+For native Xcode simulator builds, a local and configured-provider miss can
+reuse an exact completed artifact from an enabled paired build worker. Reuse
+checks the full source, toolchain, SDK, architecture and target cache key and
+verifies the downloaded archive. It needs no compilation slot. An explicit
+local build and remote build mode off skip peer lookup; other project types
+keep their existing cache paths. See `stim guide settings` for placement.
+
 ## Native Android build workers
 
 Native Gradle apps can use an approved build worker after declaring that
 Git-visible source and exact additional ignored files are sufficient. See
-`stim guide lifecycle native-android` for `android.offloadInputs`, generated
-output ownership, and supported input boundaries. Stim does not invent an artifact-cache key for
-arbitrary Gradle inputs; Gradle keeps its own incremental and task caches.
+`stim guide lifecycle native-android` for `android.offloadInputs`, generated output ownership,
+and supported input boundaries. Workers remain uncached. Local builds can opt
+into APK caching through a separate complete `android.artifactInputs` declaration.
+A configured cache provider with a `files` capability can share the verified APK
+and its receipt between machines. Private input files and environment values
+stay local; the declaration never authorizes their transfer. Gradle
+keeps its own incremental and task caches in both cases.
 
 ## Programmatic API
 
@@ -80,16 +91,64 @@ already running server. `run` builds, installs and launches.
 `build({ platform: 'ios' })` returns a retained simulator app without starting
 a device or runtime; Android returns an APK and macOS returns an app bundle.
 Build-only preserves existing sessions and uses the same cache and build locks.
+Successful builds include `result.facts.links.workspace`, an HTTPS workspace link
+agents can share with an already-paired phone or Desktop, including when the
+build machine has no Desktop app installed.
 Each result is a separate copy kept in the workspace until `stim worktree remove`.
 Run results preserve the CLI's launch evidence, including `'bundling'` and
 `'unverified'` results.
 
-Each operation uses a separate bundled worker so its home, cancellation and
-process state cannot change the importing process. The CLI and workers call
+`reload({ platform?: 'ios' | 'android' | 'web', signal? })` requests a JavaScript
+reload in a live app or reloads the owned Chrome page, returning the flat
+`stim reload --json` facts. Select a platform when more than one is live.
+Dispatch does not prove completion; verify the expected UI and inspect logs.
+A Metro broadcast can reach other connected clients. Reload uses a 60 second
+execution budget and 35 second cleanup budget, with the report timeout and
+cleanup refusals described below. Cancellation stops pending work but cannot
+retract a request already sent. Reload never retries automatically.
+
+`setSetting(key, text, { scope?, signal? })` and `unsetSetting(key, { scope?, signal? })`
+share the CLI's validation and return its JSON write result, including masked
+sensitive values. Values use CLI text syntax, including JSON for arrays and
+objects. Config lock waits and device-pool probes are asynchronous. Cancellation
+prevents a pending write; a committed write finishes its recording cleanup
+before settling. Recording changes serialize through cleanup within the home.
+
+All operations run in the importing process. `settings()` and `stats()`
+read the `stim settings --json` and `stim stats --json` payloads. All
+use the client's own home and leave the caller's cwd, environment,
+output, signal handlers and exit listeners as they were. The API and CLI call
 the same native lifecycle operations. Progress is silent unless `onProgress`
 is provided; its `message` is an output chunk. Operations accept `signal`.
-Cancellation waits for the worker to exit, and does not replace `stop()`.
+Cancellation drains the operation's owned work, and does not replace `stop()`.
 Call cleanup with a fresh signal after cancellation or partial failure.
+Cancelling `stop()` while it waits for another native operation ends that wait.
+Once teardown starts, it finishes cleanup before rejecting with `STIM_CANCELLED`;
+its config, workspace-state, and lease lock waits are asynchronous.
+
+`doctor({ platform?, record? })` and `gc({ cache?, olderThan?, worktrees? })` read their CLI
+JSON reports with a 60 second execution budget and optional `signal`. Doctor
+never repairs; its `stim.runningPath` is null. By default it does not record a
+check. Pass `record: true` to register the supported iOS/Android project and record
+its checked platforms after the report and owned cleanup succeed. Recording waits
+asynchronously for the config lock, honors `signal`, and rejects unavailable state.
+GC never
+deletes or shuts down idle devices. Reads can refresh their own usage caches
+and existing pending remote approvals. An explicit `home` or `STIM_HOME` keeps
+the CLI's scoped-home restrictions. Expiry rejects with `STIM_REPORT_TIMEOUT`
+after owned cleanup; a caller abort rejects with
+`STIM_CANCELLED`. Throwing from report progress also cancels the read.
+If child identity cannot be verified after a one-second retry budget, cleanup
+refuses with `STIM_CLAIM_UNAVAILABLE` instead of a cancellation or timeout
+error. Child cleanup errors name the launcher PID; unverifiable processes and descendants
+are left untouched. On POSIX, a launcher that exited before identity capture can only
+finish successfully once its process group is proven gone.
+After a termination request, cleanup waits at most one second for a child to
+close. Overall cleanup has a 35 second budget, including temporary-worktree
+removal; unfinished cleanup returns `STIM_CLAIM_UNAVAILABLE` and leaves
+unresolved resources in place. Credential refresh waits asynchronously and
+checks cancellation before writing.
+On Windows, report probes require the built-in Windows PowerShell for process-tree containment.
 
 `home` and `buildCache` accept absolute paths. Omit them to use normal Stim
 settings. A cache used by concurrent writers needs the same coordinating Stim
@@ -98,8 +157,29 @@ Ownership checks and cache locks remain active. `stop()` acts on this workspace,
 including resources from earlier runs, so use a dedicated workspace in CI.
 
 Stim failures are `StimError` instances with `code`, `message`, `remedy`, and
-`details`. An exception thrown by `onProgress` cancels the worker and is
-propagated unchanged.
+`details`. An exception thrown by `onProgress` stops further progress and is
+propagated unchanged: `build()` or `run()` is cancelled, and
+`stop()` or read finishes its work first.
+`logs({ tail, sources, minLevel, slot, since, grep, errorsOnly })` reads the same
+merged records as `stim logs --json`, including crash capture and agent actions.
+Pass `tail` to bound the returned records. `followLogs(options, onRecord)` emits
+that backfill and new records, then returns a stop function; aborting its signal
+also stops it. An optional third callback receives initial records instead of
+`onRecord`; its promise is awaited before the next batch. With that callback and
+no `tail`, timeline batches hold at most 500 records. Agent attribution still
+retains its matching records during backfill. These reads run in process and yield between log chunks.
+Local follow uses filesystem hints with a ten-second repair scan. While a
+directory watch is unavailable, it retries and scans every 500 ms; Expo error
+context uses a timer only while pending. Agent-action and active hosted log
+sampling are unchanged.
+Attachment schedules one 500 ms recovery scan. A moved directory on Windows can
+require the ten-second repair scan.
+Hosted targets join and leave the follow stream from local state notifications;
+missed notifications are reconciled about every 10 seconds. Active hosts still
+serve bounded log queries.
+Tail selection bounds matching timeline and agent records; agent attribution
+still reads each retained session generation to establish device ownership.
+
 `diagnostics()` returns the workspace log directory and up to 200 local records,
 even if no run has succeeded. It does not fetch remote logs or capture new crashes.
 See [the API reference](https://stim.appandflow.com/docs/programmatic-api) or

package/dist/acquire-artifact-CD4lbiWE.mjs

@@ -0,0 +1,153 @@
+import { I as waitForSharedBuild } from "./activity-BzVfHSrY.mjs";
+import { rmSync } from "node:fs";
+//#region src/engine/artifact-lifecycle.ts
+async function runArtifactLifecycle(phases) {
+	try {
+		const resolved = await phases.resolve();
+		if (resolved.kind === "ready") return resolved.artifact;
+		const cached = resolved.kind === "cached" ? resolved.artifact : await phases.claim?.() ?? null;
+		if (cached !== null) {
+			const reused = await phases.reuse(cached);
+			if (reused !== null) return reused;
+		}
+		const { build } = phases;
+		const placement = await build.placement?.select() ?? null;
+		if (placement === null) await build.admit();
+		const preparation = await build.prepare();
+		const late = await build.revalidate(preparation);
+		if (late !== null) return late.ready;
+		if (build.placement && placement !== null) {
+			const offloaded = await build.placement.acquire(placement, preparation);
+			if (offloaded !== null) return offloaded.ready;
+			await build.admit();
+		}
+		const artifact = await build.compile(placement, preparation);
+		if (await build.validate(preparation) === "cacheable") await build.store(artifact);
+		return build.finish ? await build.finish(artifact) : artifact;
+	} finally {
+		phases.release();
+	}
+}
+//#endregion
+//#region src/engine/cleanup-scope.ts
+function drain(pending, report) {
+	const kept = [];
+	for (const cleanup of pending.toReversed()) try {
+		cleanup();
+	} catch (error) {
+		kept.unshift(cleanup);
+		report(error);
+	}
+	return kept;
+}
+function createCleanupScope(report) {
+	let pending = [];
+	return {
+		defer: (cleanup) => {
+			pending.push(cleanup);
+			return () => {
+				pending = pending.filter((entry) => entry !== cleanup);
+			};
+		},
+		transfer: () => {
+			let handed = pending;
+			pending = [];
+			return () => {
+				handed = drain(handed, report);
+			};
+		},
+		release: () => {
+			pending = drain(pending, report);
+		}
+	};
+}
+//#endregion
+//#region src/engine/acquire-artifact.ts
+async function acquireArtifact(adapter, { root, logFile, deps }) {
+	const owned = createCleanupScope((error) => adapter.temporaryReleaseFailed(error));
+	let closeOffload = null;
+	let buildLock = null;
+	let buildSlot = null;
+	const releaseLock = () => {
+		if (!buildLock) return;
+		const held = buildLock;
+		buildLock = null;
+		try {
+			deps.releaseBuildLock(held);
+		} catch (error) {
+			adapter.releaseFailed(`the build lock at ${held.path}`, error);
+		}
+	};
+	const releaseSlot = () => {
+		if (!buildSlot) return;
+		const held = buildSlot;
+		buildSlot = null;
+		try {
+			deps.releaseBuildSlot(held);
+		} catch (error) {
+			adapter.releaseFailed("the build slot", error);
+		}
+	};
+	const run = {
+		own: (directory) => owned.defer(() => rmSync(directory, {
+			recursive: true,
+			force: true
+		})),
+		openOffload: (close) => {
+			closeOffload = close;
+		},
+		claimSharedBuild: async (options) => {
+			const shared = await waitForSharedBuild({
+				...options,
+				platform: adapter.platform,
+				root,
+				logFile,
+				command: adapter.command,
+				acquire: deps.acquireBuildLock,
+				wait: deps.waitForBuild,
+				now: deps.now
+			});
+			if (!shared.refusal) buildLock = shared.lock;
+			return shared;
+		},
+		takeBuildSlot: async (options) => {
+			buildSlot = await deps.acquireBuildSlot({
+				...options,
+				root,
+				logFile
+			});
+			return buildSlot;
+		}
+	};
+	try {
+		return {
+			ok: true,
+			artifact: await runArtifactLifecycle({
+				...adapter.lifecycle(run),
+				release: () => {
+					const close = closeOffload;
+					closeOffload = null;
+					try {
+						close?.();
+					} finally {
+						releaseLock();
+						releaseSlot();
+					}
+				}
+			}),
+			release: owned.transfer()
+		};
+	} catch (error) {
+		await adapter.settleFailed?.();
+		const failure = adapter.refuse(error);
+		if (failure === null) throw error;
+		return {
+			ok: false,
+			failure
+		};
+	} finally {
+		owned.release();
+	}
+}
+//#endregion
+export { acquireArtifact as t };