@stim-cli/ci 0.0.0-stage → 1.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janic Duplessis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# @stim-cli/ci
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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
+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.
+
+## 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 run --platform android --project ./app --artifacts ./test-results --timeout 1800 -- pnpm test:e2e
+```
+
+`--platform` accepts `ios`, `android`, `macos`, or `web`. `--project` defaults
+to the current directory. `--home` and `--build-cache` explicitly select the
+Stim home and native artifact cache; leaving them unset preserves normal Stim
+configuration. The CLI uses each project's normal build settings. The library
+also accepts the public API's platform-specific run options.
+
+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'`.
+
+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        |
+
+`run.json` contains the public Stim result `{ platform, facts }`, including
+platform-specific process, target, cache, launch, and log facts. 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.
+Keep results outside fingerprinted project inputs.
+
+The result includes `version: 1`, `projectRoot`, `platform`, `artifactsDir`,
+`resultPath`, `runPath`, `startedAt`, `durationMs`, `exitCode`, the native `run`,
+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
+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
+compiler and process output even when setup fails. These persisted files can
+include earlier records from the same workspace. Collection does not follow
+symlinks, nested directories, or paths referenced by log records. It does not
+copy build binaries or caches. Collection failures appear in `diagnostics.error`
+without replacing the setup or test exit code.
+
+Providers can import `diagnosticArtifactFiles` from `@stim-cli/ci/artifacts` to
+list the regular result, run, test and diagnostic files for upload. The helper
+only selects those known files and the copied logs; custom test outputs need
+the provider's own explicit upload configuration.
+
+## Library
+
+```ts
+import { runCI } from '@stim-cli/ci';
+
+const result = await runCI({
+  projectRoot: '/checkout/app',
+  run: { platform: 'ios', configuration: 'Debug' },
+  command: ['pnpm', 'test:e2e'],
+  artifactsDir: '/job/results',
+  timeoutMs: 30 * 60 * 1000,
+  signal: controller.signal,
+  onProgress: ({ message }) => process.stderr.write(message),
+});
+
+process.exitCode = result.exitCode;
+```
+
+The library does not change `process.cwd()`, `process.env`, process signal
+handlers, or the caller's exit code. Invalid arguments throw before native
+setup. Setup, test, diagnostics, and cleanup outcomes are returned in the
+result. The CLI alone handles SIGINT/SIGTERM and sets its exit code.
+
+## Failure and cancellation
+
+A failing command preserves its exit code even when diagnostics or cleanup
+also fail. A passing command followed by incomplete cleanup returns 1. The
+result records both failures when relevant. Diagnostics failures are recorded
+without replacing the setup or test result.
+
+`timeoutMs` / `--timeout` covers setup and the test command; there is no timeout
+by default. Timeout returns 124. Cancellation returns 130. Cancellation during
+cleanup is also recorded, preserving an already completed test failure. Cancellation stops
+the test process tree and aborts the native operation, then uses fresh signals
+to stop the workspace (up to 60 seconds) and collect its persisted diagnostics
+(up to 10 seconds). On macOS/Linux, the test command gets its own process group; children
+that deliberately detach from it are outside that group. On Windows, tree
+termination uses `taskkill`; commands must not leave background children after
+their parent exits. Keep test resources inside the command's process tree.
+
+Cleanup cannot run after SIGKILL, runner loss, or a provider's hard timeout.
+Leave room between the package timeout and the job timeout. The result reports
+incomplete cleanup; use normal Stim recovery for a persistent runner. `stop`
+shuts down owned devices; it does not delete them.
+
+## Disposable and shared runners
+
+GitHub-hosted jobs need no home or cache configuration. When `GITHUB_ACTIONS=true`,
+`RUNNER_ENVIRONMENT=github-hosted` and `RUNNER_TEMP` is set, the package defaults to
+`$RUNNER_TEMP/stim-ci/home` and `$RUNNER_TEMP/stim-ci/build-cache`. Repeated steps
+in the same job reuse these paths. The public API and test command receive the
+same paths without changing the caller's environment.
+
+An explicit `home` / `--home` or `STIM_HOME` retains the caller's home and normal
+cache configuration. An explicit `buildCache` / `--build-cache` or
+`STIM_BUILD_CACHE` overrides the automatic cache path. Self-hosted runners,
+other providers and local runs keep normal Stim configuration and configured
+build/device caps. `CI=true` alone changes no defaults or coordination guarantees.
+
+For another disposable runner dedicated to one job, explicitly provide a fresh
+job home and a job-local artifact cache:
+
+```sh
+stim-ci run --platform ios --project ./app \
+  --home "$RUNNER_TEMP/stim-home" \
+  --build-cache "$RUNNER_TEMP/stim-build-cache" \
+  --artifacts "$RUNNER_TEMP/stim-results" \
+  --timeout 1800 -- pnpm test:e2e
+```
+
+Restore and save only the artifact cache through the provider. Never restore
+workspace state, process records, claims, device ledgers, or pairings. Use cache
+names that separate OS, architecture and platform; Stim still validates its
+native fingerprint/configuration keys. Keep provider fallback keys within
+compatible toolchains. Save complete entries, not staging directories, after
+the runner finishes. Cache service failure should fall back to a build.
+
+Do not point independent homes at a shared writable filesystem cache. Build
+single-flight claims are scoped to the Stim home. Job-local restored copies
+have no cross-job writers; persistent shared runners should use their normal
+shared Stim home and coordination.
+
+Current code already skips capacity admission when `concurrency.maxBuilds` and
+`concurrency.maxDevices` are 0, their defaults. An explicit `STIM_HOME` defaults
+device parking to 0. These are existing fast paths, not a new unsafe mode.
+Ownership ledgers, atomic writes, process identity, cache publication, and
+workspace claims still run. No timing study has established that this
+bookkeeping is a material CI cost.
+
+One concrete setup waste in Stim's existing Android fixture workflow is booting
+an emulator through another action and immediately killing it before Stim
+boots its own. SDK-only setup can avoid that extra boot without adopting an
+external device. External simulator/emulator adoption is not part of this API.
+
+Before adding coordination shortcuts, compare cold and warm runs by phase:
+dependency setup, fingerprint/cache lookup, native build, device boot, install,
+Metro, test, diagnostics, cleanup, and capacity waits. Validate a fresh-home
+warm-cache run actually skips compilation, a deliberate test failure retains
+its logs/exit code, cancellation leaves no live owned processes, and a shared
+runner's unrelated workspace remains running. Native timings and cross-provider
+acceptance require real tool runs; unit tests are not that evidence.

package/dist/artifacts.d.mts

@@ -0,0 +1,7 @@
+//#region src/artifacts.d.ts
+/** Copies regular, non-symlink log files directly inside the public diagnostics directory. */
+declare function copyDiagnosticLogs(directory: string, artifactsDir: string): Promise<string[]>;
+/** Lists CI result, test and diagnostic evidence from an explicit root, excluding linked entries and app binaries. */
+declare function diagnosticArtifactFiles(artifactsDir: string): Promise<string[]>;
+//#endregion
+export { copyDiagnosticLogs, diagnosticArtifactFiles };

package/dist/artifacts.mjs

@@ -0,0 +1,48 @@
+import { constants } from "node:fs";
+import { join } from "node:path";
+import { copyFile, lstat, mkdir, readdir, realpath } from "node:fs/promises";
+//#region src/artifacts.ts
+async function regularFiles(directory, resolveDirectory = false) {
+	try {
+		if (resolveDirectory) directory = await realpath(directory);
+		if (!(await lstat(directory)).isDirectory()) return [];
+		return (await readdir(directory, { withFileTypes: true })).filter((entry) => entry.isFile()).map((entry) => entry.name).toSorted();
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+function isLog(name) {
+	return /\.(?:log|ndjson)(?:\.1)?$/.test(name);
+}
+/** Copies regular, non-symlink log files directly inside the public diagnostics directory. */
+async function copyDiagnosticLogs(directory, artifactsDir) {
+	const names = (await regularFiles(directory)).filter(isLog);
+	const destination = join(artifactsDir, "logs");
+	if (names.length) {
+		await mkdir(destination, { recursive: true });
+		if (!(await lstat(destination)).isDirectory()) throw new Error("Diagnostic logs destination must be a regular directory.");
+	}
+	const files = [];
+	for (const name of names) {
+		const target = join(destination, name);
+		await copyFile(join(directory, name), target, constants.COPYFILE_EXCL);
+		files.push(target);
+	}
+	return files;
+}
+/** Lists CI result, test and diagnostic evidence from an explicit root, excluding linked entries and app binaries. */
+async function diagnosticArtifactFiles(artifactsDir) {
+	const reports = /* @__PURE__ */ new Set([
+		"result.json",
+		"run.json",
+		"diagnostics.json",
+		"test.stdout.log",
+		"test.stderr.log"
+	]);
+	const files = (await regularFiles(artifactsDir, true)).filter((name) => reports.has(name)).map((name) => join(artifactsDir, name));
+	const logs = join(artifactsDir, "logs");
+	return [...files, ...(await regularFiles(logs)).filter(isLog).map((name) => join(logs, name))];
+}
+//#endregion
+export { copyDiagnosticLogs, diagnosticArtifactFiles };

package/dist/cli-RvPAkat7.mjs

@@ -0,0 +1,80 @@
+import { t as runCI } from "./src-BdobdbxB.mjs";
+import { parseArgs } from "node:util";
+//#region src/cli.ts
+const HELP = `Usage: stim-ci run --platform <ios|android|macos|web> [options] -- <command> [args...]
+
+Build and launch an app, run a test command, collect diagnostics, and stop it.
+The final result is JSON on stdout; progress and test output go to stderr.
+
+Options:
+  --project <path>       Project directory (default: current directory)
+  --artifacts <path>     Results directory (default: a fresh temporary directory)
+  --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)
+  --help                Show this help
+  --version             Show the package version
+`;
+function parse(argv) {
+	const separator = argv.indexOf("--");
+	if (separator < 0) throw new Error("Separate the test command with --.");
+	const command = argv.slice(separator + 1);
+	if (!command[0]) throw new Error("A test command is required after --.");
+	const { values, positionals } = parseArgs({
+		args: argv.slice(0, separator),
+		allowPositionals: true,
+		options: {
+			platform: { type: "string" },
+			project: { type: "string" },
+			artifacts: { type: "string" },
+			home: { type: "string" },
+			"build-cache": { type: "string" },
+			timeout: { type: "string" }
+		}
+	});
+	if (positionals.length !== 1 || positionals[0] !== "run") throw new Error("Expected stim-ci run.");
+	const platform = values.platform;
+	if (platform !== "ios" && platform !== "android" && platform !== "macos" && platform !== "web") throw new Error("--platform must be ios, android, macos or web.");
+	const timeoutMs = values.timeout === void 0 ? void 0 : Number(values.timeout) * 1e3;
+	return {
+		projectRoot: values.project ?? process.cwd(),
+		run: { platform },
+		command,
+		artifactsDir: values.artifacts,
+		home: values.home,
+		buildCache: values["build-cache"],
+		timeoutMs
+	};
+}
+async function main(argv = process.argv.slice(2)) {
+	if (argv.length === 1 && argv[0] === "--version") {
+		process.stdout.write(`1.19.0\n`);
+		return;
+	}
+	if (argv.length === 0 || argv[0] === "--help" || argv[0] === "run" && argv[1] === "--help") {
+		process.stdout.write(HELP);
+		return;
+	}
+	const controller = new AbortController();
+	const interrupt = () => controller.abort();
+	try {
+		const options = parse(argv);
+		process.on("SIGINT", interrupt);
+		process.on("SIGTERM", interrupt);
+		const result = await runCI({
+			...options,
+			signal: controller.signal,
+			onProgress: ({ message }) => process.stderr.write(message)
+		});
+		process.stdout.write(`${JSON.stringify(result)}\n`);
+		process.exitCode = result.exitCode;
+	} catch (error) {
+		process.stderr.write(`stim-ci: ${error.message}\n`);
+		process.exitCode = 1;
+	} finally {
+		process.off("SIGINT", interrupt);
+		process.off("SIGTERM", interrupt);
+	}
+}
+//#endregion
+export { main };

package/dist/index.d.mts

@@ -0,0 +1,57 @@
+import { StimOptions, StimRunOptions, StimRunResult, StimStopResult } from "stim";
+//#region src/command.d.ts
+interface CommandResult {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  durationMs: number;
+  stdout: string;
+  stderr: string;
+  error?: string;
+}
+//#endregion
+//#region src/index.d.ts
+type WithoutSignal<T> = T extends unknown ? Omit<T, "signal"> : never;
+interface CIOptions {
+  projectRoot: string;
+  run: WithoutSignal<StimRunOptions>;
+  command: readonly [string, ...string[]];
+  artifactsDir?: string;
+  home?: string;
+  buildCache?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  onProgress?: StimOptions["onProgress"];
+}
+interface CIFailure {
+  code: string;
+  message: string;
+  remedy?: string;
+}
+interface CIResult {
+  version: 1;
+  projectRoot: string;
+  platform: StimRunOptions["platform"];
+  artifactsDir: string;
+  resultPath: string;
+  runPath: string;
+  startedAt: string;
+  durationMs: number;
+  exitCode: number;
+  run: StimRunResult | null;
+  test: CommandResult | null;
+  failure?: CIFailure;
+  reportingError?: CIFailure;
+  diagnostics: {
+    path: string | null;
+    files?: string[];
+    error?: CIFailure;
+  };
+  cleanup: {
+    result: StimStopResult | null;
+    error?: CIFailure;
+  };
+}
+/** Runs an app and argv-based test command, stops its workspace or explicit slot, and retains diagnostics. */
+declare function runCI(options: CIOptions): Promise<CIResult>;
+//#endregion
+export { CIFailure, CIOptions, CIResult, type CommandResult, runCI };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { t as runCI } from "./src-BdobdbxB.mjs";
+export { runCI };

package/dist/src-BdobdbxB.mjs

@@ -0,0 +1,291 @@
+import { copyDiagnosticLogs } from "./artifacts.mjs";
+import { closeSync, mkdirSync, mkdtempSync, openSync, readdirSync, realpathSync, renameSync, writeFileSync, writeSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { createStim } from "stim";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import spawn from "cross-spawn";
+//#region src/command.ts
+async function runCommand({ command, cwd, env, artifactsDir, signal, onOutput }) {
+	signal?.throwIfAborted();
+	const started = Date.now();
+	const stdout = join(artifactsDir, "test.stdout.log");
+	const stderr = join(artifactsDir, "test.stderr.log");
+	const out = openSync(stdout, "w");
+	let err;
+	try {
+		err = openSync(stderr, "w");
+		const child = spawn(command[0], command.slice(1), {
+			cwd,
+			env,
+			detached: process.platform !== "win32",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			windowsHide: true
+		});
+		let error;
+		let groupError;
+		let killTimer;
+		const kill = (force) => {
+			if (!child.pid) return;
+			if (process.platform === "win32") spawn.sync("taskkill", [
+				"/pid",
+				String(child.pid),
+				"/t",
+				...force ? ["/f"] : []
+			], {
+				stdio: "ignore",
+				windowsHide: true
+			});
+			else try {
+				process.kill(-child.pid, force ? "SIGKILL" : "SIGTERM");
+			} catch (caught) {
+				if (caught.code !== "ESRCH") groupError ??= String(caught);
+			}
+		};
+		const terminate = () => {
+			if (killTimer) return;
+			kill(false);
+			killTimer = setTimeout(() => kill(true), 1e3);
+		};
+		const output = (stream, fd, chunk) => {
+			try {
+				writeSync(fd, chunk);
+				onOutput?.({
+					stream,
+					message: chunk.toString("utf8")
+				});
+			} catch (caught) {
+				error ??= String(caught);
+				terminate();
+			}
+		};
+		child.stdout.on("data", (chunk) => output("stdout", out, chunk));
+		child.stderr.on("data", (chunk) => output("stderr", err, chunk));
+		child.on("error", (caught) => {
+			error ??= caught.message;
+		});
+		child.once("exit", terminate);
+		signal?.addEventListener("abort", terminate, { once: true });
+		if (signal?.aborted) terminate();
+		try {
+			const status = await new Promise((resolve) => {
+				child.once("close", (exitCode, exitSignal) => {
+					resolve({
+						exitCode,
+						signal: exitSignal
+					});
+				});
+			});
+			if (process.platform !== "win32" && child.pid) {
+				const deadline = Date.now() + 2e3;
+				while (true) {
+					try {
+						process.kill(-child.pid, 0);
+					} catch (caught) {
+						const code = caught.code;
+						if (code === "ESRCH") break;
+						if (code !== "EPERM") {
+							error ??= String(caught);
+							break;
+						}
+						groupError ??= String(caught);
+					}
+					if (Date.now() >= deadline) {
+						error ??= groupError ?? `Test process group ${child.pid} did not exit after termination`;
+						break;
+					}
+					await setTimeout$1(20);
+				}
+			}
+			return {
+				...status,
+				durationMs: Date.now() - started,
+				stdout,
+				stderr,
+				...error ? { error } : {}
+			};
+		} finally {
+			signal?.removeEventListener("abort", terminate);
+			clearTimeout(killTimer);
+		}
+	} finally {
+		closeSync(out);
+		if (err !== void 0) closeSync(err);
+	}
+}
+//#endregion
+//#region src/index.ts
+function failure(error, code) {
+	const caught = error;
+	return {
+		code: typeof caught?.code === "string" ? caught.code : code,
+		message: typeof caught?.message === "string" ? caught.message : String(error),
+		...typeof caught?.remedy === "string" ? { remedy: caught.remedy } : {}
+	};
+}
+function writeJson(path, value) {
+	const pending = `${path}.tmp`;
+	writeFileSync(pending, `${JSON.stringify(value, null, 2)}\n`);
+	renameSync(pending, path);
+}
+function commandEnvironment(result, options) {
+	const facts = result.run.facts;
+	return {
+		...process.env,
+		...options.home ? { STIM_HOME: resolve(options.home) } : {},
+		...options.buildCache ? { STIM_BUILD_CACHE: resolve(options.buildCache) } : {},
+		STIM_CI_PLATFORM: result.platform,
+		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
+	};
+}
+/** Runs an app and 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.timeoutMs !== void 0 && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0)) throw new Error("timeoutMs must be a positive integer.");
+	if (process.env.GITHUB_ACTIONS === "true" && process.env.RUNNER_ENVIRONMENT === "github-hosted" && process.env.RUNNER_TEMP && !options.home && !process.env.STIM_HOME) {
+		const directory = join(resolve(process.env.RUNNER_TEMP), "stim-ci");
+		options = {
+			...options,
+			home: join(directory, "home"),
+			buildCache: options.buildCache || (process.env.STIM_BUILD_CACHE ? void 0 : join(directory, "build-cache"))
+		};
+	}
+	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 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;
+	const started = Date.now();
+	const result = {
+		version: 1,
+		projectRoot,
+		platform: options.run.platform,
+		artifactsDir,
+		resultPath: join(artifactsDir, "result.json"),
+		runPath: join(artifactsDir, "run.json"),
+		startedAt: new Date(started).toISOString(),
+		durationMs: 0,
+		exitCode: 1,
+		run: null,
+		test: null,
+		diagnostics: { path: null },
+		cleanup: { result: null }
+	};
+	let cleaningUp = false;
+	const onProgress = options.onProgress ? (event) => {
+		try {
+			options.onProgress(event);
+		} catch (error) {
+			result.reportingError ??= failure(error, "STIM_CI_REPORT_FAILED");
+			if (!cleaningUp) throw error;
+		}
+	} : void 0;
+	const stim = createStim({
+		projectRoot,
+		home: options.home ? resolve(options.home) : void 0,
+		buildCache: options.buildCache ? resolve(options.buildCache) : void 0,
+		onProgress
+	});
+	let attempted = false;
+	try {
+		signal?.throwIfAborted();
+		attempted = true;
+		result.run = await stim.run({
+			...options.run,
+			signal
+		});
+		signal?.throwIfAborted();
+		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}`}.`
+		};
+	} catch (error) {
+		result.failure = failure(error, result.run ? "STIM_CI_TEST_FAILED" : "STIM_CI_SETUP_FAILED");
+	} finally {
+		cleaningUp = true;
+		if (signal?.aborted) {
+			const timedOut = timeout?.aborted && !options.signal?.aborted;
+			result.exitCode = timedOut ? 124 : 130;
+			result.failure = {
+				code: timedOut ? "STIM_CI_TIMEOUT" : "STIM_CI_CANCELLED",
+				message: timedOut ? `CI run exceeded ${options.timeoutMs}ms.` : "CI run was cancelled."
+			};
+		}
+		if (attempted) {
+			try {
+				result.cleanup.result = await stim.stop({
+					..."slot" in options.run ? { slot: options.run.slot } : {},
+					signal: AbortSignal.timeout(6e4)
+				});
+				if (!result.cleanup.result.ok) result.cleanup.error = {
+					code: "STIM_CI_CLEANUP_FAILED",
+					message: "Stim could not stop the workspace."
+				};
+			} catch (error) {
+				result.cleanup.error = failure(error, "STIM_CI_CLEANUP_FAILED");
+			}
+			try {
+				const diagnostics = await stim.diagnostics({
+					tail: 1e3,
+					signal: AbortSignal.timeout(1e4)
+				});
+				const path = join(artifactsDir, "diagnostics.json");
+				writeJson(path, diagnostics);
+				result.diagnostics.path = path;
+				result.diagnostics.files = await copyDiagnosticLogs(diagnostics.directory, artifactsDir);
+			} catch (error) {
+				result.diagnostics.error = failure(error, "STIM_CI_DIAGNOSTICS_FAILED");
+			}
+			if (options.signal?.aborted && result.exitCode === 0) {
+				result.exitCode = 130;
+				result.failure = {
+					code: "STIM_CI_CANCELLED",
+					message: "CI run was cancelled."
+				};
+			}
+			if (result.cleanup.error && result.exitCode === 0) {
+				result.exitCode = 1;
+				result.failure = result.cleanup.error;
+			}
+		}
+		if (result.reportingError && result.exitCode === 0) {
+			result.exitCode = 1;
+			result.failure = result.reportingError;
+		}
+		result.durationMs = Date.now() - started;
+		try {
+			writeJson(result.resultPath, result);
+		} catch (error) {
+			result.reportingError = failure(error, "STIM_CI_REPORT_FAILED");
+			if (result.exitCode === 0) {
+				result.exitCode = 1;
+				result.failure = result.reportingError;
+			}
+		}
+	}
+	return result;
+}
+//#endregion
+export { runCI as t };

package/dist/stim-ci.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/stim-ci.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+//#region bin/node-check.ts
+const parts = process.versions.node.split(".").map(Number);
+const major = parts[0] ?? 0;
+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-RvPAkat7.mjs").then(({ main }) => main());
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@stim-cli/ci",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.19.0",
+  "description": "Run Stim apps and test commands in CI with diagnostics and scoped cleanup.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appandflow/stim.git",
+    "directory": "packages/ci"
+  },
+  "bin": {
+    "stim-ci": "dist/stim-ci.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "module-sync": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./artifacts": {
+      "types": "./dist/artifacts.d.mts",
+      "module-sync": "./dist/artifacts.mjs",
+      "default": "./dist/artifacts.mjs"
+    }
+  },
+  "dependencies": {
+    "cross-spawn": "^7.0.6",
+    "stim": "^1.19.0"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
 }