@stim-cli/ci 1.36.0 → 1.38.0

package/README.md

@@ -36,6 +36,22 @@ device with `STIM_NO_RECORDED_BUILD`, and the failure's `remedy` names the comma
 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.
@@ -93,6 +109,13 @@ 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'`.
 
+Without `--`, `run` installs and launches the app, writes `run.json`, then stops the
+workspace as after a passing test, with `test: null` and exit code 0. Use it when a
+later step drives a Release app on the device `run.json` names; boot a simulator again
+by its UDID, since cleanup shuts it down. Cleanup also stops Metro, so a Debug app has
+no bundler in that later step. An explicit `--` with no command after it is
+refused. The library's `runCI` behaves the same when `command` is omitted.
+
 The test process runs in the project directory. It receives the caller's
 environment plus these values:
 
@@ -126,7 +149,7 @@ the `test` result, optional `failure`, `diagnostics`, and `cleanup`.
 If a progress callback or writing `result.json` fails, the result includes
 `reportingError`. Reporter failures cannot interrupt cleanup or replace an earlier
 test failure; after a passing test, they return 1.
-Setup failure leaves `run` and `test` null. Diagnostics include the last 1000
+Setup failure leaves `run` and `test` null; a run without a command leaves `test` null. Diagnostics include the last 1000
 structured records and their original directory. After cleanup, regular `.log`
 and `.ndjson` files (including `.1` rotated copies) directly inside that directory
 are copied into `logs/` and listed in `diagnostics.files`. This retains raw

package/dist/{cli-BhFWDeM1.mjs → cli-BKK3T47P.mjs}

@@ -1,13 +1,14 @@
-import { n as buildCI, t as runCI } from "./src-Gwd9CN7Z.mjs";
+import { n as buildCI, t as runCI } from "./src-DJH6gv01.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...]
+       stim-ci run --platform <ios|android|macos|web> [options] [-- <command> [args...]]
 
 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.
+Run installs and launches the app the last matching build recorded, runs the test command
+given after --, if any, 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.
 
@@ -110,8 +111,7 @@ function parse(argv) {
 			}
 		};
 	}
-	if (separator < 0) throw new Error("Separate the test command with --.");
-	if (!command[0]) throw new Error("A test command is required after --.");
+	if (separator >= 0 && !command[0]) throw new Error("A test command is required after --.");
 	const run = platform === "ios" ? {
 		platform,
 		scheme: values.scheme,
@@ -125,13 +125,13 @@ function parse(argv) {
 		options: {
 			...common,
 			run,
-			command
+			...separator >= 0 ? { command } : {}
 		}
 	};
 }
 async function main(argv = process.argv.slice(2)) {
 	if (argv.length === 1 && argv[0] === "--version") {
-		process.stdout.write(`1.36.0\n`);
+		process.stdout.write(`1.38.0\n`);
 		return;
 	}
 	if (argv.length === 0 || argv[0] === "--help" || (argv[0] === "run" || argv[0] === "build") && argv[1] === "--help") {

package/dist/index.d.mts

@@ -22,9 +22,10 @@ interface CommandResult {
 }
 //#endregion
 //#region src/build.d.ts
-type WithoutSignal<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<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;
 }
@@ -56,8 +57,9 @@ declare function buildCI(input: CIBuildOptions): Promise<CIBuildResult>;
 type WithoutKeys<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 interface CIOptions extends CIContextOptions {
   /** 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" | "easProfile">;
-  command: readonly [string, ...string[]];
+  run: WithoutKeys<StimRunOptions, "signal" | "recordedBuild" | "cleanAppState" | "easProfile">;
+  /** Test command argv. Without it, `runCI` installs and launches the app, then stops it as after a passing test. */
+  command?: readonly [string, ...string[]];
 }
 interface CIFailure {
   code: string;
@@ -88,7 +90,7 @@ interface CIResult {
     error?: CIFailure;
   };
 }
-/** Runs an app and argv-based test command, stops its workspace or explicit slot, and retains diagnostics. */
+/** Runs an app and an optional argv-based test command, stops its workspace or explicit slot, and retains diagnostics. */
 declare function runCI(options: CIOptions): Promise<CIResult>;
 //#endregion
 export { type CIBuildOptions, type CIBuildResult, CIFailure, CIOptions, CIResult, type CommandResult, buildCI, runCI };

package/dist/index.mjs

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

package/dist/{src-Gwd9CN7Z.mjs → src-DJH6gv01.mjs}

@@ -201,6 +201,7 @@ async function buildCI(input) {
 		attempted = true;
 		result.build = await stim.build({
 			...options.build,
+			remoteBuild: "local",
 			signal
 		});
 		signal?.throwIfAborted();
@@ -296,10 +297,10 @@ function commandEnvironment(result, options) {
 		STIM_CI_RUN_RESULT: result.runPath ?? ""
 	};
 }
-/** Runs an app and argv-based test command, stops its workspace or explicit slot, and retains diagnostics. */
+/** Runs an app and an optional argv-based test command, stops its workspace or explicit slot, and retains diagnostics. */
 async function runCI(options) {
-	if (!options.command[0]) throw new Error("A non-empty test command is required.");
-	for (const argument of options.command) if (typeof argument !== "string" || argument.includes("\0")) throw new Error("Test command arguments must be strings without null bytes.");
+	if (options.command && !options.command[0]) throw new Error("A non-empty test command is required.");
+	for (const argument of options.command ?? []) if (typeof argument !== "string" || argument.includes("\0")) throw new Error("Test command arguments must be strings without null bytes.");
 	const prepared = prepareCI(options);
 	options = prepared.options;
 	const { projectRoot, artifactsDir, timeout, signal } = prepared;
@@ -341,26 +342,30 @@ async function runCI(options) {
 		result.run = await stim.run({
 			...options.run,
 			recordedBuild: true,
+			cleanAppState: true,
 			signal
 		});
 		signal?.throwIfAborted();
 		if (result.runPath) writeJson(result.runPath, result.run);
-		result.test = await runCommand({
-			command: options.command,
-			cwd: projectRoot,
-			env: commandEnvironment(result, options),
-			artifactsDir,
-			signal,
-			onOutput: onProgress
-		});
-		result.exitCode = result.test.exitCode ?? 1;
-		if (result.exitCode < 0 || result.exitCode === 0 && result.test.error) result.exitCode = 1;
-		if (result.exitCode !== 0) result.failure = {
-			code: "STIM_CI_TEST_FAILED",
-			message: result.test.error ?? `Test command ${result.test.signal ? `was terminated by ${result.test.signal}` : `exited with ${result.exitCode}`}.`
-		};
+		if (!options.command) result.exitCode = 0;
+		else {
+			result.test = await runCommand({
+				command: options.command,
+				cwd: projectRoot,
+				env: commandEnvironment(result, options),
+				artifactsDir,
+				signal,
+				onOutput: onProgress
+			});
+			result.exitCode = result.test.exitCode ?? 1;
+			if (result.exitCode < 0 || result.exitCode === 0 && result.test.error) result.exitCode = 1;
+			if (result.exitCode !== 0) result.failure = {
+				code: "STIM_CI_TEST_FAILED",
+				message: result.test.error ?? `Test command ${result.test.signal ? `was terminated by ${result.test.signal}` : `exited with ${result.exitCode}`}.`
+			};
+		}
 	} catch (error) {
-		result.failure = failure(error, result.run ? "STIM_CI_TEST_FAILED" : "STIM_CI_SETUP_FAILED");
+		result.failure = failure(error, result.run && options.command ? "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;

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-BhFWDeM1.mjs").then(({ main }) => main());
+} else import("./cli-BKK3T47P.mjs").then(({ main }) => main());
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/ci",
-  "version": "1.36.0",
+  "version": "1.38.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.36.0"
+    "stim": "1.38.0"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6"