stim 1.17.2 → 1.19.0

package/README.md

@@ -1,6 +1,6 @@
 # Stim
 
-The `stim` npm package installs the `stim` command.
+The `stim` npm package installs the `stim` command and exports a typed lifecycle API.
 
 Stim gives coding agents fast, isolated React Native and Expo environments. Each
 project or git worktree gets its own Metro port and owned device. Shared caches
@@ -36,6 +36,55 @@ 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.
 
+## Programmatic API
+
+Install `stim` as a dependency with `npm install --save-dev stim`, then import
+from the main package:
+
+```ts
+import { createStim } from 'stim';
+
+const stim = createStim({ projectRoot: process.cwd() });
+try {
+  const result = await stim.run({ platform: 'ios' });
+  console.log(result.facts.udid);
+} finally {
+  try {
+    console.log(await stim.diagnostics({ errors: true }));
+  } finally {
+    const cleanup = await stim.stop();
+    if (!cleanup.ok) throw new Error(cleanup.summary);
+  }
+}
+```
+
+`run` supports iOS and Android React Native/Expo apps, SwiftPM macOS apps, and
+web pages with the same requirements as their CLI commands. Web runs require an
+already running server. `run` builds, installs and launches; there is no
+build-only API yet. It preserves 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
+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()`.
+Call cleanup with a fresh signal after cancellation or partial failure.
+
+`home` and `buildCache` accept absolute paths. Omit them to use normal Stim
+settings. A cache used by concurrent writers needs the same coordinating Stim
+home; do not point independent homes at a concurrently writable artifact cache.
+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.
+`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
+`stim guide api` for options and result types.
+
 ## Documentation
 
 The [documentation website](https://stim.appandflow.com/) is the full

package/dist/{activity-IRvJY_ru.mjs → activity-BSw0x84R.mjs}

@@ -1,7 +1,7 @@
-import { t as getExecutor } from "./exec-CaErVv7t.mjs";
-import { t as process_identity_exports } from "./process-identity-BmRm1qV0.mjs";
-import { r as readWorkspaceState$1, x as workspaceLogsDir$1 } from "./workspace-state-DqcCbpE7.mjs";
-import { i as listLeaseFiles, r as leaseIsExpired } from "./device-lease-DpoS36_u.mjs";
+import { t as process_identity_exports } from "./process-identity-Biv3arCO.mjs";
+import { t as getExecutor } from "./exec-i8GDPwq9.mjs";
+import { r as readWorkspaceState$1, x as workspaceLogsDir$1 } from "./workspace-state-CR9X86xJ.mjs";
+import { i as listLeaseFiles, r as leaseIsExpired } from "./device-lease-Cu7PtQpZ.mjs";
 import { closeSync, fstatSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { agentDeviceStateDirs, readViewedDevices } from "@stim-cli/core/state";

package/dist/{agent-device-usage-output-BK41vnzN.mjs → agent-device-usage-output-Bjxu_VmX.mjs}

@@ -1,16 +1,16 @@
-import { t as getExecutor } from "./exec-CaErVv7t.mjs";
-import { j as formatBytes } from "./config-D0DbpZtM.mjs";
-import { t as process_identity_exports } from "./process-identity-BmRm1qV0.mjs";
-import { o as formatLongDuration } from "./command-output-CDAIFD-8.mjs";
-import { a as envDir, l as processMatches, s as parseAgentDeviceRecord } from "./activity-IRvJY_ru.mjs";
-import { c as listWorkspaceDirs } from "./workspaces-Bcib97-6.mjs";
-import { randomUUID } from "node:crypto";
+import { t as process_identity_exports } from "./process-identity-Biv3arCO.mjs";
+import { t as getExecutor } from "./exec-i8GDPwq9.mjs";
+import { o as formatLongDuration } from "./command-output-Bt8ygHE7.mjs";
+import { j as formatBytes } from "./config-DC5jEtd1.mjs";
+import { c as listWorkspaceDirs } from "./workspaces-Djb2gfi9.mjs";
+import { a as envDir, l as processMatches, s as parseAgentDeviceRecord } from "./activity-BSw0x84R.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { configDir } from "@stim-cli/core";
 import { agentDeviceUsageFile, readAgentDeviceUsageCache, readSwiftpmCacheUsage, swiftpmCacheUsageFile } from "@stim-cli/core/state";
 import { homedir } from "node:os";
 import chalk from "chalk";
+import { configDir } from "@stim-cli/core";
+import { randomUUID } from "node:crypto";
 //#region src/devices/report-only-usage.ts
 function canonical(path) {
 	try {