@stim-cli/ci 1.35.0 → 1.37.0

package/README.md

@@ -1,8 +1,8 @@
 # @stim-cli/ci
 
-Build and launch an app through Stim, run your test command, retain diagnostics,
-and stop the workspace. The library imports the public API from `stim`; it does
-not depend on GitHub Actions, EAS, or internal Stim modules.
+Build an app once, then install and launch it through Stim, run your test
+command and stop the workspace. The library imports the public API from `stim`;
+it does not depend on GitHub Actions, EAS, or internal Stim modules.
 
 Requires Node.js 22.12 or newer and the native tools for the selected platform.
 Install the app's dependencies before running it. Each concurrent CI run needs
@@ -10,50 +10,78 @@ its own checkout. The run stops that checkout's workspace, including resources
 started before a build failure; an explicit API `run.slot` limits cleanup to
 that slot. Do not point CI at a developer's active checkout.
 
-## Build only
+## Build, then run
+
+`stim-ci build` is the only step that compiles. `stim-ci run` never compiles:
 
 ```sh
-npx --yes --package @stim-cli/ci stim-ci build --platform ios --project ./app --artifacts ./build-results
+npx --yes --package @stim-cli/ci stim-ci build --platform ios --project ./app
+npx --yes --package @stim-cli/ci stim-ci run --platform ios --project ./app -- pnpm test:e2e
 ```
 
-This compiles or restores an artifact without starting a simulator, emulator,
-Metro server, or app. It does not stop an existing workspace session. iOS builds
-target the simulator; archives, device distribution and web compilation are
-not supported. By default, iOS and Android builds use the same native artifact
-cache as `run`. A later `run` in the same job validates that cache normally; its
-`run.json` reports `cacheKey` and `cacheHit`, which show whether it reused the
-build. Android reuse requires the run's emulator system image to have the host's
-ABI; a configured `android.systemImage` with another ABI, or a physical device,
-misses. An iOS Debug build with `--arch all` is keyed without an architecture,
-so a later Debug `run` misses. macOS builds are not cached, so a later macOS
-`run` builds again.
-
-The result has `stage: "build"`, `build`, `buildPath`, and `artifactPath`.
-The results directory contains `build.json`, `result.json`, `diagnostics.json`,
-and `app.apk` for Android or `app.tar.gz` for iOS/macOS. iOS and macOS also
-keep the archive command's output in `artifact.stdout.log` and
-`artifact.stderr.log`. The archive preserves app
-executable permissions and symlinks when uploaded through an artifact service.
-Extract it with `tar -xzf app.tar.gz`. Importing a downloaded artifact into a
-Stim run is not part of this command.
-
-The library exports `buildCI({ projectRoot, build: { platform: "ios" }, ... })`.
-It accepts the same home/cache, timeout, cancellation and progress options as
-`runCI`. Build cancellation waits for the owned build operation to finish
-cleanup and retains diagnostics; it never calls workspace `stop()`. A cancel or timeout after the artifact is exported does not fail the build
-stage.
+`build` compiles or restores the app from the native artifact cache, without
+starting a simulator, emulator, Metro server, or app, and without stopping an
+existing workspace session. It records the resulting app in the checkout's Stim
+state (the workspace state under the Stim home) for the platform and selectors:
+iOS scheme and configuration, Android variant. A later `build` with the same
+selectors replaces the record. Architecture and ABI are build-only; the last build
+for the selectors wins whatever its architecture.
+
+`run` installs and launches the recorded app exactly as built, then runs the
+test. It does not fingerprint, consult the cache, build or replace the app's JS:
+it trusts the recorded build, so rebuild after changing the project. A Debug app
+loads its JS from Metro, which `run` starts as before. With no recorded build for
+the selectors (or after its app was removed), `run` refuses before touching a
+device with `STIM_NO_RECORDED_BUILD`, and the failure's `remedy` names the command
+to run first, such as `stim-ci build --platform ios --scheme App`. `build` and
+`run` must use the same Stim home: pass the same `--home`, or keep the default.
+
+Every iOS and Android `run` on this machine starts the app from clean state on
+the workspace's own simulator or emulator, including when the device already
+has this build.
+Before it installs, `run` uninstalls every other user app except XCUITest
+runner apps, such as the ones agent-device installs. On iOS it also clears the
+app's defaults and data container and resets the simulator keychain; on Android
+it runs `pm clear` on the app. Simulator-wide settings such as privacy grants
+are kept. A local simulator or emulator Stim does not own refuses with
+`STIM_BAD_ARG` instead of skipping the cleanup. A run that `ios.remote` or
+`android.remote` places on another machine or on EAS is not cleaned, and a
+physical device is refused. `build` always compiles on this machine and ignores
+`remote.build`. By default it compiles an iOS app, and an Android Debug app,
+for this machine's architecture only, so when `run` can land on another
+machine or on EAS, build
+for that device too with `--arch all` (iOS) or `--abi all` (Android).
+
+`--eas-profile <name>` (iOS and Android, build only) downloads a completed EAS
+development build instead of compiling, as `stim ios --eas-profile` does; `run`
+then installs it. Stim never starts an EAS build.
+
+macOS and web are unchanged: `run --platform macos` builds its app itself and web
+has no native build. iOS builds target the simulator; archives, device
+distribution and web compilation are not supported.
+
+`build` exports nothing by default. `--export <path>` also writes the app there:
+`app.apk` for Android, a tar.gz for iOS and macOS that preserves executable
+permissions and symlinks (extract with `tar -xzf`). On a cache hit the archive is
+the slowest part of `build`, so export only when something consumes the file.
+
+The build result has `stage: "build"`, `build`, `buildPath`, and `artifactPath`
+(the export, or null). With `--artifacts` the directory also contains
+`build.json`, `result.json` and `diagnostics.json`.
+
+The library exports `buildCI({ projectRoot, build: { platform: "ios" }, exportPath, ... })`
+and `runCI`. `runCI`'s `run` option takes the selectors of the build to run; build-only
+options such as `easProfile` belong to `buildCI`. Build cancellation waits for the
+owned build operation to finish cleanup and retains diagnostics; it never calls
+workspace `stop()`. A cancel or timeout after the export is written does not fail
+the build stage.
 
 ## Command line
 
-Without installing:
-
-```sh
-npx --yes --package @stim-cli/ci stim-ci run --platform ios --project ./app -- pnpm test:e2e
-```
-
 Or install `npm install --global @stim-cli/ci`, then:
 
 ```sh
+stim-ci build --platform android --project ./app
 stim-ci run --platform android --project ./app --artifacts ./test-results --timeout 1800 -- pnpm test:e2e
 ```
 
@@ -62,20 +90,21 @@ to the current directory. `--home` and `--build-cache` explicitly select the
 Stim home and native artifact cache; leaving them unset preserves normal Stim
 configuration.
 
-Without selectors, the CLI uses each project's normal build settings. `build`
-and `run` accept the same selectors as the public API, so a run can match a
-build:
+Without selectors, the CLI uses each project's normal build settings. `run`
+must use the selectors its `build` used to find the recorded app:
 
-| Option                   | Platform | Stage      | Selects                                                 |
-| ------------------------ | -------- | ---------- | ------------------------------------------------------- |
-| `--scheme <name>`        | iOS      | build, run | Xcode scheme                                            |
-| `--configuration <name>` | iOS      | build, run | Xcode configuration                                     |
-| `--variant <name>`       | Android  | build, run | Gradle variant                                          |
-| `--arch <name>`          | iOS      | build      | Architecture: `arm64`, `x86_64`, `all`                  |
-| `--abi <name>`           | Android  | build      | ABI: `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`, `all` |
+| Option                   | Platform     | Stage      | Selects                                                 |
+| ------------------------ | ------------ | ---------- | ------------------------------------------------------- |
+| `--scheme <name>`        | iOS          | build, run | Xcode scheme                                            |
+| `--configuration <name>` | iOS          | build, run | Xcode configuration                                     |
+| `--variant <name>`       | Android      | build, run | Gradle variant                                          |
+| `--arch <name>`          | iOS          | build      | Architecture: `arm64`, `x86_64`, `all`                  |
+| `--abi <name>`           | Android      | build      | ABI: `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`, `all` |
+| `--eas-profile <name>`   | iOS, Android | build      | Download this EAS profile's development build           |
+| `--export <path>`        | all native   | build      | Also write the app (APK or tar.gz) to this path         |
 
-The library also accepts the public API's other platform-specific build and run
-options.
+The library also accepts the public API's other platform-specific build options, and
+run options other than those that build.
 
 Everything after `--` is an argument vector. No shell is inferred. To use shell
 syntax, pass a shell explicitly: `-- bash -e -o pipefail -c 'pnpm test:e2e'`.
@@ -83,25 +112,28 @@ syntax, pass a shell explicitly: `-- bash -e -o pipefail -c 'pnpm test:e2e'`.
 The test process runs in the project directory. It receives the caller's
 environment plus these values:
 
-| Variable                | Value                                                        |
-| ----------------------- | ------------------------------------------------------------ |
-| `STIM_CI_PLATFORM`      | Selected platform                                            |
-| `STIM_CI_DEVICE_ID`     | Exact simulator UDID or emulator serial; empty for macOS/web |
-| `STIM_CI_APP_ID`        | App bundle/package identifier when available                 |
-| `STIM_CI_METRO_PORT`    | Metro port when available                                    |
-| `STIM_CI_ARTIFACTS_DIR` | Absolute results directory                                   |
-| `STIM_CI_RUN_RESULT`    | Path to `run.json`, written before the command starts        |
+| Variable                | Value                                                                     |
+| ----------------------- | ------------------------------------------------------------------------- |
+| `STIM_CI_PLATFORM`      | Selected platform                                                         |
+| `STIM_CI_DEVICE_ID`     | Exact simulator UDID or emulator serial; empty for macOS/web              |
+| `STIM_CI_APP_ID`        | App bundle/package identifier when available                              |
+| `STIM_CI_METRO_PORT`    | Metro port when available                                                 |
+| `STIM_CI_ARTIFACTS_DIR` | Absolute results directory; empty without `--artifacts`                   |
+| `STIM_CI_RUN_RESULT`    | Path to `run.json` before the command starts; empty without `--artifacts` |
 
 `run.json` contains the public Stim result `{ platform, facts }`, including
-platform-specific process, target, cache, launch, and log facts. Use the exact
+platform-specific process, target, launch, and log facts; `appPath` is the stable
+path of the installed app. Use the exact
 reported target; do not select an arbitrary booted device. Tests own
 app-specific readiness checks. A launch can still be `bundling` or `unverified`.
 
-Progress and test output go to stderr. Stdout contains one JSON result. The same
-result is saved as `result.json` beside `run.json`, `test.stdout.log`,
-`test.stderr.log`, and `diagnostics.json`. Without `--artifacts`, results use a
-fresh temporary directory. An explicit results directory must be empty; a reused
-directory is refused before setup so stale evidence cannot describe a new run.
+Progress and test output go to stderr. Stdout contains one JSON result. With
+`--artifacts <dir>` the same result is saved as `result.json` beside `run.json`,
+`test.stdout.log`, `test.stderr.log`, and `diagnostics.json`. Without it no result,
+test or diagnostic file is written, no logs are copied, and the result's
+`artifactsDir`, `resultPath` and `runPath` are null. An explicit results directory
+must be empty; a reused directory is refused before setup so stale evidence cannot
+describe a new run.
 Keep results outside fingerprinted project inputs.
 
 The result includes `version: 1`, `projectRoot`, `platform`, `artifactsDir`,
@@ -188,6 +220,9 @@ For another disposable runner dedicated to one job, explicitly provide a fresh
 job home and a job-local artifact cache:
 
 ```sh
+stim-ci build --platform ios --project ./app \
+  --home "$RUNNER_TEMP/stim-home" \
+  --build-cache "$RUNNER_TEMP/stim-build-cache"
 stim-ci run --platform ios --project ./app \
   --home "$RUNNER_TEMP/stim-home" \
   --build-cache "$RUNNER_TEMP/stim-build-cache" \

package/dist/{cli-BujO5iDm.mjs → cli-BCFk6LoD.mjs}

@@ -1,16 +1,19 @@
-import { n as buildCI, t as runCI } from "./src-q52NuL5J.mjs";
+import { n as buildCI, t as runCI } from "./src-CFd6F73i.mjs";
 import { parseArgs } from "node:util";
 //#region src/cli.ts
 const HELP = `Usage: stim-ci build --platform <ios|android|macos> [options]
        stim-ci run --platform <ios|android|macos|web> [options] -- <command> [args...]
 
-Build exports an artifact without starting or stopping an app.
-Run builds and launches an app, runs a test command, collects diagnostics, and stops it.
-The final result is JSON on stdout; progress and test output go to stderr.
+Build is the only step that compiles. It records the app for this checkout, platform and
+selectors, and exports it only with --export.
+Run installs and launches the app the last matching build recorded, runs a test command, and
+stops the app. It never builds; with no recorded build it refuses and names the build to run.
+The final result is JSON on stdout; progress and test output go to stderr. No result, test or
+diagnostic file is written unless --artifacts is given.
 
 Options:
   --project <path>       Project directory (default: current directory)
-  --artifacts <path>     Results directory (default: a fresh temporary directory)
+  --artifacts <path>     Empty directory for result, test and diagnostic files (default: write none)
   --home <path>          Explicit Stim home (default: job-local on GitHub-hosted runners)
   --build-cache <path>   Native artifact cache directory
   --timeout <seconds>    Setup and test timeout (cleanup has its own deadline)
@@ -22,7 +25,9 @@ Build selectors (build and run):
   --configuration <name> iOS configuration
   --variant <name>       Android variant
 
-Build-only selectors:
+Build-only options:
+  --eas-profile <name>   Download this EAS profile's completed development build instead of compiling
+  --export <path>        Also write the app here: an APK for Android, a tar.gz for iOS and macOS
   --arch <name>          iOS architecture: arm64, x86_64, all
   --abi <name>           Android ABI: arm64-v8a, armeabi-v7a, x86, x86_64, all
 `;
@@ -43,7 +48,9 @@ function parse(argv) {
 			configuration: { type: "string" },
 			variant: { type: "string" },
 			arch: { type: "string" },
-			abi: { type: "string" }
+			abi: { type: "string" },
+			"eas-profile": { type: "string" },
+			export: { type: "string" }
 		}
 	});
 	const stage = positionals[0];
@@ -58,11 +65,17 @@ function parse(argv) {
 		buildCache: values["build-cache"],
 		timeoutMs
 	};
-	if (stage === "run" && (values.arch !== void 0 || values.abi !== void 0)) throw new Error("--arch and --abi only apply to build-only.");
+	for (const flag of [
+		"arch",
+		"abi",
+		"eas-profile",
+		"export"
+	]) if (stage === "run" && values[flag] !== void 0) throw new Error(`--${flag} only applies to build.`);
+	if (values["eas-profile"] !== void 0 && platform !== "ios" && platform !== "android") throw new Error("--eas-profile only applies to iOS and Android.");
 	if (platform !== "ios" && (values.scheme !== void 0 || values.configuration !== void 0 || values.arch !== void 0)) throw new Error("--scheme, --configuration and --arch only apply to iOS.");
 	if (platform !== "android" && (values.variant !== void 0 || values.abi !== void 0)) throw new Error("--variant and --abi only apply to Android.");
 	if (stage === "build") {
-		if (separator >= 0) throw new Error("Build-only does not take a test command. Use stim-ci run to launch and test.");
+		if (separator >= 0) throw new Error("Build does not take a test command. Use stim-ci run to launch and test.");
 		if (platform === "web") throw new Error("Web projects have no native build artifact. Use stim-ci run --platform web.");
 		if (values.arch !== void 0 && ![
 			"arm64",
@@ -80,17 +93,20 @@ function parse(argv) {
 			platform,
 			scheme: values.scheme,
 			configuration: values.configuration,
-			arch: values.arch
+			arch: values.arch,
+			easProfile: values["eas-profile"]
 		} : platform === "android" ? {
 			platform,
 			variant: values.variant,
-			abi: values.abi
+			abi: values.abi,
+			easProfile: values["eas-profile"]
 		} : { platform };
 		return {
 			stage,
 			options: {
 				...common,
-				build
+				build,
+				exportPath: values.export
 			}
 		};
 	}
@@ -115,7 +131,7 @@ function parse(argv) {
 }
 async function main(argv = process.argv.slice(2)) {
 	if (argv.length === 1 && argv[0] === "--version") {
-		process.stdout.write(`1.35.0\n`);
+		process.stdout.write(`1.37.0\n`);
 		return;
 	}
 	if (argv.length === 0 || argv[0] === "--help" || (argv[0] === "run" || argv[0] === "build") && argv[1] === "--help") {

package/dist/index.d.mts

@@ -2,6 +2,7 @@ import { StimBuildOptions, StimBuildResult, StimOptions, StimRunOptions, StimRun
 //#region src/context.d.ts
 interface CIContextOptions {
   projectRoot: string;
+  /** Writes result, test and diagnostic files here; without it nothing is written. */
   artifactsDir?: string;
   home?: string;
   buildCache?: string;
@@ -15,25 +16,28 @@ interface CommandResult {
   exitCode: number | null;
   signal: NodeJS.Signals | null;
   durationMs: number;
-  stdout: string;
-  stderr: string;
+  stdout: string | null;
+  stderr: string | null;
   error?: string;
 }
 //#endregion
 //#region src/build.d.ts
-type WithoutSignal$1<T> = T extends unknown ? Omit<T, "signal"> : never;
+type WithoutKeys$1<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 interface CIBuildOptions extends CIContextOptions {
-  build: WithoutSignal$1<StimBuildOptions>;
+  /** Always compiles on this machine; `remoteBuild` is not accepted. */
+  build: WithoutKeys$1<StimBuildOptions, "signal" | "remoteBuild">;
+  /** Also writes the app here as a portable APK (Android) or tar.gz (iOS, macOS); without it the build is only recorded for `run`. */
+  exportPath?: string;
 }
 interface CIBuildResult {
   version: 1;
   stage: "build";
   projectRoot: string;
   platform: StimBuildOptions["platform"];
-  artifactsDir: string;
-  resultPath: string;
-  buildPath: string;
-  /** Portable APK or tar.gz bundle preserving executable permissions and symlinks. */
+  artifactsDir: string | null;
+  resultPath: string | null;
+  buildPath: string | null;
+  /** The exported APK or tar.gz bundle preserving executable permissions and symlinks; null unless an export was requested. */
   artifactPath: string | null;
   startedAt: string;
   durationMs: number;
@@ -46,13 +50,14 @@ interface CIBuildResult {
     error?: CIFailure;
   };
 }
-/** Builds and exports an artifact without starting or stopping a workspace runtime. */
+/** Builds the app and records it for `runCI` without starting or stopping a workspace runtime. */
 declare function buildCI(input: CIBuildOptions): Promise<CIBuildResult>;
 //#endregion
 //#region src/index.d.ts
-type WithoutSignal<T> = T extends unknown ? Omit<T, "signal"> : never;
+type WithoutKeys<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 interface CIOptions extends CIContextOptions {
-  run: WithoutSignal<StimRunOptions>;
+  /** Selectors of the recorded build to run. `run` never builds, so build-time options such as `easProfile` belong to `buildCI`. */
+  run: WithoutKeys<StimRunOptions, "signal" | "recordedBuild" | "cleanAppState" | "easProfile">;
   command: readonly [string, ...string[]];
 }
 interface CIFailure {
@@ -64,9 +69,9 @@ interface CIResult {
   version: 1;
   projectRoot: string;
   platform: StimRunOptions["platform"];
-  artifactsDir: string;
-  resultPath: string;
-  runPath: string;
+  artifactsDir: string | null;
+  resultPath: string | null;
+  runPath: string | null;
   startedAt: string;
   durationMs: number;
   exitCode: number;

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { n as buildCI, t as runCI } from "./src-q52NuL5J.mjs";
+import { n as buildCI, t as runCI } from "./src-CFd6F73i.mjs";
 export { buildCI, runCI };

package/dist/{src-q52NuL5J.mjs → src-CFd6F73i.mjs}

@@ -1,6 +1,5 @@
 import { copyDiagnosticLogs } from "./artifacts.mjs";
-import { closeSync, copyFileSync, mkdirSync, mkdtempSync, openSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, writeSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { closeSync, copyFileSync, mkdirSync, openSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, writeSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { createStim } from "stim";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -30,9 +29,11 @@ function prepareCI(options) {
 		};
 	}
 	const projectRoot = realpathSync(options.projectRoot);
-	const artifactsDir = options.artifactsDir ? resolve(options.artifactsDir) : mkdtempSync(join(tmpdir(), "stim-ci-"));
-	mkdirSync(artifactsDir, { recursive: true });
-	if (readdirSync(artifactsDir).length > 0) throw new Error(`Artifacts directory must be empty: ${artifactsDir}. Choose a new directory for this run.`);
+	const artifactsDir = options.artifactsDir ? resolve(options.artifactsDir) : null;
+	if (artifactsDir) {
+		mkdirSync(artifactsDir, { recursive: true });
+		if (readdirSync(artifactsDir).length > 0) throw new Error(`Artifacts directory must be empty: ${artifactsDir}. Choose a new directory for this run.`);
+	}
 	const timeout = options.timeoutMs === void 0 ? void 0 : AbortSignal.timeout(options.timeoutMs);
 	const signals = [options.signal, timeout].filter((value) => value !== void 0);
 	const signal = signals.length ? AbortSignal.any(signals) : void 0;
@@ -49,12 +50,12 @@ function prepareCI(options) {
 async function runCommand({ command, cwd, env, artifactsDir, logName = "test", signal, onOutput }) {
 	signal?.throwIfAborted();
 	const started = Date.now();
-	const stdout = join(artifactsDir, `${logName}.stdout.log`);
-	const stderr = join(artifactsDir, `${logName}.stderr.log`);
-	const out = openSync(stdout, "w");
+	const stdout = artifactsDir ? join(artifactsDir, `${logName}.stdout.log`) : null;
+	const stderr = artifactsDir ? join(artifactsDir, `${logName}.stderr.log`) : null;
+	const out = stdout ? openSync(stdout, "w") : void 0;
 	let err;
 	try {
-		err = openSync(stderr, "w");
+		if (stderr) err = openSync(stderr, "w");
 		const child = spawn(command[0], command.slice(1), {
 			cwd,
 			env,
@@ -93,7 +94,7 @@ async function runCommand({ command, cwd, env, artifactsDir, logName = "test", s
 		};
 		const output = (stream, fd, chunk) => {
 			try {
-				writeSync(fd, chunk);
+				if (fd !== void 0) writeSync(fd, chunk);
 				onOutput?.({
 					stream,
 					message: chunk.toString("utf8")
@@ -153,13 +154,13 @@ async function runCommand({ command, cwd, env, artifactsDir, logName = "test", s
 			clearTimeout(killTimer);
 		}
 	} finally {
-		closeSync(out);
+		if (out !== void 0) closeSync(out);
 		if (err !== void 0) closeSync(err);
 	}
 }
 //#endregion
 //#region src/build.ts
-/** Builds and exports an artifact without starting or stopping a workspace runtime. */
+/** Builds the app and records it for `runCI` without starting or stopping a workspace runtime. */
 async function buildCI(input) {
 	const { options, projectRoot, artifactsDir, timeout, signal } = prepareCI(input);
 	const started = Date.now();
@@ -169,8 +170,8 @@ async function buildCI(input) {
 		projectRoot,
 		platform: options.build.platform,
 		artifactsDir,
-		resultPath: join(artifactsDir, "result.json"),
-		buildPath: join(artifactsDir, "build.json"),
+		resultPath: artifactsDir ? join(artifactsDir, "result.json") : null,
+		buildPath: artifactsDir ? join(artifactsDir, "build.json") : null,
 		artifactPath: null,
 		startedAt: new Date(started).toISOString(),
 		durationMs: 0,
@@ -200,16 +201,16 @@ async function buildCI(input) {
 		attempted = true;
 		result.build = await stim.build({
 			...options.build,
+			remoteBuild: "local",
 			signal
 		});
 		signal?.throwIfAborted();
-		writeJson(result.buildPath, result.build);
-		if (result.build.platform === "android") {
-			exporting = join(artifactsDir, "app.apk");
-			copyFileSync(result.build.facts.apkPath, exporting);
-		} else {
+		if (result.buildPath) writeJson(result.buildPath, result.build);
+		if (input.exportPath) exporting = resolve(input.exportPath);
+		if (exporting) mkdirSync(dirname(exporting), { recursive: true });
+		if (exporting && result.build.platform === "android") copyFileSync(result.build.facts.apkPath, exporting);
+		else if (exporting && result.build.platform !== "android") {
 			const bundle = result.build.platform === "ios" ? result.build.facts.appPath : result.build.facts.bundle;
-			exporting = join(artifactsDir, "app.tar.gz");
 			const packed = await runCommand({
 				command: [
 					"tar",
@@ -233,7 +234,7 @@ async function buildCI(input) {
 			if (packed.exitCode !== 0 || packed.error) throw Object.assign(new Error(packed.error ?? `Artifact export exited with ${packed.exitCode}.`), { code: "STIM_CI_ARTIFACT_FAILED" });
 		}
 		signal?.throwIfAborted();
-		result.artifactPath = exporting;
+		result.artifactPath = exporting ?? null;
 		result.exitCode = 0;
 	} catch (error) {
 		result.failure = failure(error, result.build ? "STIM_CI_ARTIFACT_FAILED" : "STIM_CI_BUILD_FAILED");
@@ -253,7 +254,7 @@ async function buildCI(input) {
 		} catch (error) {
 			result.reportingError ??= failure(error, "STIM_CI_REPORT_FAILED");
 		}
-		if (attempted) try {
+		if (attempted && artifactsDir) try {
 			const diagnostics = await stim.diagnostics({
 				tail: 1e3,
 				signal: AbortSignal.timeout(1e4)
@@ -268,7 +269,7 @@ async function buildCI(input) {
 			result.failure = result.reportingError;
 		}
 		result.durationMs = Date.now() - started;
-		try {
+		if (result.resultPath) try {
 			writeJson(result.resultPath, result);
 		} catch (error) {
 			result.reportingError = failure(error, "STIM_CI_REPORT_FAILED");
@@ -292,8 +293,8 @@ function commandEnvironment(result, options) {
 		STIM_CI_DEVICE_ID: String("udid" in facts ? facts.udid : "serial" in facts ? facts.serial ?? "" : ""),
 		STIM_CI_APP_ID: String("bundleId" in facts ? facts.bundleId ?? "" : ""),
 		STIM_CI_METRO_PORT: String("metroPort" in facts ? facts.metroPort ?? "" : ""),
-		STIM_CI_ARTIFACTS_DIR: result.artifactsDir,
-		STIM_CI_RUN_RESULT: result.runPath
+		STIM_CI_ARTIFACTS_DIR: result.artifactsDir ?? "",
+		STIM_CI_RUN_RESULT: result.runPath ?? ""
 	};
 }
 /** Runs an app and argv-based test command, stops its workspace or explicit slot, and retains diagnostics. */
@@ -309,8 +310,8 @@ async function runCI(options) {
 		projectRoot,
 		platform: options.run.platform,
 		artifactsDir,
-		resultPath: join(artifactsDir, "result.json"),
-		runPath: join(artifactsDir, "run.json"),
+		resultPath: artifactsDir ? join(artifactsDir, "result.json") : null,
+		runPath: artifactsDir ? join(artifactsDir, "run.json") : null,
 		startedAt: new Date(started).toISOString(),
 		durationMs: 0,
 		exitCode: 1,
@@ -340,10 +341,12 @@ async function runCI(options) {
 		attempted = true;
 		result.run = await stim.run({
 			...options.run,
+			recordedBuild: true,
+			cleanAppState: true,
 			signal
 		});
 		signal?.throwIfAborted();
-		writeJson(result.runPath, result.run);
+		if (result.runPath) writeJson(result.runPath, result.run);
 		result.test = await runCommand({
 			command: options.command,
 			cwd: projectRoot,
@@ -360,6 +363,7 @@ async function runCI(options) {
 		};
 	} catch (error) {
 		result.failure = failure(error, result.run ? "STIM_CI_TEST_FAILED" : "STIM_CI_SETUP_FAILED");
+		if (result.failure.code === "STIM_NO_RECORDED_BUILD") result.failure.remedy = `Run ${buildCommand(options, projectRoot)} first.`;
 	} finally {
 		cleaningUp = true;
 		if (signal?.aborted) {
@@ -383,7 +387,7 @@ async function runCI(options) {
 			} catch (error) {
 				result.cleanup.error = failure(error, "STIM_CI_CLEANUP_FAILED");
 			}
-			try {
+			if (artifactsDir) try {
 				const diagnostics = await stim.diagnostics({
 					tail: 1e3,
 					signal: AbortSignal.timeout(1e4)
@@ -412,7 +416,7 @@ async function runCI(options) {
 			result.failure = result.reportingError;
 		}
 		result.durationMs = Date.now() - started;
-		try {
+		if (result.resultPath) try {
 			writeJson(result.resultPath, result);
 		} catch (error) {
 			result.reportingError = failure(error, "STIM_CI_REPORT_FAILED");
@@ -424,5 +428,16 @@ async function runCI(options) {
 	}
 	return result;
 }
+function buildCommand({ run, home, buildCache }, projectRoot) {
+	const flags = [`--platform ${run.platform}`];
+	if (projectRoot !== realpathSync(process.cwd())) flags.push(`--project ${JSON.stringify(projectRoot)}`);
+	if (home) flags.push(`--home ${JSON.stringify(resolve(home))}`);
+	if (buildCache) flags.push(`--build-cache ${JSON.stringify(resolve(buildCache))}`);
+	if (run.platform === "ios") {
+		if (run.scheme !== void 0) flags.push(`--scheme ${JSON.stringify(run.scheme)}`);
+		if (run.configuration !== void 0) flags.push(`--configuration ${JSON.stringify(run.configuration)}`);
+	} else if (run.platform === "android" && run.variant !== void 0) flags.push(`--variant ${JSON.stringify(run.variant)}`);
+	return `stim-ci build ${flags.join(" ")}`;
+}
 //#endregion
 export { buildCI as n, runCI as t };

package/dist/stim-ci.mjs

@@ -6,6 +6,6 @@ const minor = parts[1] ?? 0;
 if (major < 22 || major === 22 && minor < 12) {
 	process.stderr.write(`stim-ci requires Node.js 22.12.0 or later; this is ${process.versions.node}.\n`);
 	process.exitCode = 1;
-} else import("./cli-BujO5iDm.mjs").then(({ main }) => main());
+} else import("./cli-BCFk6LoD.mjs").then(({ main }) => main());
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/ci",
-  "version": "1.35.0",
+  "version": "1.37.0",
   "description": "Build Stim app artifacts or run Stim apps and test commands in CI with diagnostics and scoped cleanup.",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "cross-spawn": "^7.0.6",
-    "stim": "1.35.0"
+    "stim": "1.37.0"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6"