stim 0.0.0 → 1.0.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

@@ -0,0 +1,150 @@
+# Stim
+
+The `stim` npm package installs the `stim` command.
+
+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
+keep native and JavaScript builds warm across worktrees.
+
+## Install
+
+If you previously installed `stim-cli` globally, follow the
+[migration instructions](#migrating-from-stim-cli) first.
+
+```bash
+npm install --global stim
+npx skills add appandflow/stim
+```
+
+Run without a global install when needed:
+
+```bash
+npx stim <command>
+```
+
+Node 20.19.4 or later on Node 20, or Node 22.12.0 or later, is required.
+
+Machine defaults in `~/.stim/config.json` can enable or disable native artifact
+caching, remote caches, Metro sharing, iOS compiler caching and prefix mapping,
+and Android ccache/CAS, PCH, Gradle caching, and target ABI narrowing. Optional
+`.stim.json` runtime overrides apply per app, beside its `package.json`; monorepo
+apps do not inherit the repository-root file. Worktree-copy rules stay at the
+repository root. Run `stim guide settings` for the
+`optimizations` schema; existing defaults remain unchanged.
+
+## Normal workflow
+
+```bash
+stim doctor
+stim start
+stim ios                  # or: stim android
+stim logs --errors
+stim stop
+```
+
+For `stim logs --errors`, a clean check requires exit code 0 and no matching
+errors in the captured logs. Exit code 0 alone means the query succeeded, even
+when it prints errors; an empty result does not prove launch or log capture
+succeeded.
+
+Use `stim start --reset-cache` to recover from stale Metro transforms or file-map
+state. It restarts only this app's verified owned Metro, keeping its port and
+devices. A fresh persistent cache namespace bypasses old entries without deleting
+shared stores or changing other apps or native build caches. Expo requires SDK
+54+ and Stim's config adapter. See `stim guide lifecycle` for scope and limitations.
+
+Use `stim doctor --platform ios` or `stim doctor --platform android` when only
+one native platform is in scope; shared project checks still run. Doctor also
+prints the running CLI version and the `stim` installation resolved from PATH,
+and flags a resolved installation that is older than another available one.
+
+For stale Android CMake launcher findings, stop native builds and run
+`stim doctor --fix --platform android` in the affected checkout. It clears
+affected ignored, untracked generated `.cxx` configurations in the app and
+installed native modules, then reports remaining findings. The next build
+recreates that output; source files, custom launcher settings, and shared
+ccache entries are preserved. Its cache-lock check cannot detect uncached,
+release-swap fallback, or direct Gradle builds; stop all native builds first.
+
+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.
+
+Use `stim ios --scheme "App Staging"` when a project has several shared Xcode
+app schemes. Combine it with `--configuration Release` if needed. Without the
+flag, Stim keeps its automatic scheme selection. Explicit schemes use separate
+artifact caches and Xcode build directories; run `stim guide lifecycle builds`
+for provider behavior. This selects an Xcode scheme, not a URL scheme.
+
+Launch evidence does not prove that the UI is interactive. Apps can optionally
+[declare readiness with two debug log messages](https://appandflow.github.io/stim/docs/dev-server-and-logs#optional-app-declared-readiness),
+without a package or SDK. A captured pending message extends the default
+three-second stability window after bundle delivery to a bounded wait for ready.
+Managed Metro response capture distinguishes a finished build from a finished
+response; servers without capture use the build-complete marker. Run
+`stim guide lifecycle readiness` for implementation instructions; verify the
+expected screen separately.
+
+`stim reload [ios|android]` requests a JavaScript reload in the live app on this
+workspace's owned local device. Use it after a failed first bundle load, when
+an error screen remains after a fix, or when you explicitly need an app
+restart. It is not part of the normal workflow and does not build, install,
+boot, or launch an app. The platform is optional when only one app is live.
+Success confirms that the request was sent; Stim does not observe completion.
+Verify the expected UI on the reported device and inspect `stim logs --errors`
+before claiming recovery.
+
+For an isolated branch, create the worktree with Git, then warm it:
+
+```bash
+git worktree add -b feature/settings ../feature-settings HEAD
+cd ../feature-settings
+stim worktree warm
+```
+
+If a harness already created the linked worktree, run only `stim worktree warm`
+there. Warm copies missing ignored state from main, including eligible `.env`
+and local configuration files. Existing entries are preserved; existing
+ignored directories such as `node_modules` are skipped whole.
+
+Wait for warm to finish before editing, installing dependencies, starting
+Metro/builds, or running another warm in that worktree. Concurrent writes are
+unsafe: entries created after the initial check can be overwritten or removed.
+
+After the work is preserved, `stim worktree remove` removes any linked
+worktree, warmed or not. Git-created branches stay. See the
+[worktree guide](https://appandflow.github.io/stim/docs/worktrees) for exclusions
+and cleanup rules.
+
+## Reference
+
+The [documentation website](https://appandflow.github.io/stim/) explains the
+human workflow and all commands.
+
+The installed CLI contains version-matched operational guidance:
+
+```bash
+stim guide agent
+stim --help
+stim <command> --help
+stim guide
+```
+
+Runtime state defaults to `~/.stim`. Set `STIM_HOME` to move it. Stim manages
+owned simulators and emulators, leases connected physical devices, and supports
+configured remote devices.
+
+## Migrating from stim-cli
+
+Remove the old global package before installing `stim`, since both provide the
+same command:
+
+```bash
+npm uninstall --global stim-cli
+npm install --global stim
+```
+
+Update programmatic imports from `stim-cli/cache-manifest` to
+`stim/cache-manifest`. The `@stim-cli/*` packages keep their names.
+
+MIT License.

package/dist/android-cas-compiler.d.mts

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

package/dist/android-cas-compiler.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { t as getExecutor } from "./exec-bsN9MJXb.mjs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { once } from "node:events";
+//#region bin/android-cas-compiler.ts
+const context = process.env.STIM_ANDROID_CAS_CONTEXT;
+if (!context) throw new Error("Missing STIM_ANDROID_CAS_CONTEXT. Run this build through stim android.");
+const config = JSON.parse(readFileSync(context, "utf8"));
+const args = process.argv.slice(2);
+const cxx = process.argv[1].endsWith("++");
+const compiler = cxx ? config.clangxx : config.clang;
+const extra = ["-resource-dir", config.resourceDir];
+if (cxx) extra.push("-nostdinc++", "-isystem", join(config.ndk, "toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr/include/c++/v1"));
+if (!args.some((arg) => [
+	"-c",
+	"-E",
+	"-S"
+].includes(arg))) extra.push(`--ld-path=${config.lld}`);
+if (args.includes("-c")) {
+	const cwd = process.cwd();
+	const overlays = join(config.state, "vfs");
+	mkdirSync(overlays, { recursive: true });
+	const overlay = join(overlays, `${createHash("sha256").update(cwd).digest("hex")}.json`);
+	if (!existsSync(overlay)) {
+		const temporary = `${overlay}.${randomUUID()}.tmp`;
+		writeFileSync(temporary, JSON.stringify({
+			version: 0,
+			"use-external-names": false,
+			roots: [{
+				type: "directory-remap",
+				name: "/^src",
+				"external-contents": config.source
+			}, {
+				type: "directory-remap",
+				name: "/^build",
+				"external-contents": cwd
+			}]
+		}));
+		renameSync(temporary, overlay);
+	}
+	extra.push("-ivfsoverlay", overlay, "-fdepscan=inline", "-fdepscan-include-tree", "-Xclang", "-fcas-path", "-Xclang", config.cache, "-Rcompile-job-cache", `-fdepscan-prefix-map=${config.source}=/^src`, `-fdepscan-prefix-map=${cwd}=/^build`, `-fdepscan-prefix-map=${config.state}=/^state`);
+}
+const started = performance.now();
+const child = getExecutor().spawn(compiler, [...extra, ...args], { stdio: [
+	"inherit",
+	"pipe",
+	"pipe"
+] });
+let stderr = "";
+child.stdout.on("data", (chunk) => process.stdout.write(chunk));
+child.stderr.on("data", (chunk) => {
+	stderr += chunk.toString();
+	process.stderr.write(chunk);
+});
+const [code] = await once(child, "close");
+appendFileSync(join(config.state, "compiler.jsonl"), `${JSON.stringify({
+	argv: [
+		compiler,
+		...extra,
+		...args
+	],
+	cwd: process.cwd(),
+	code,
+	seconds: (performance.now() - started) / 1e3,
+	stderr
+})}\n`);
+process.exitCode = code ?? 1;
+//#endregion
+export {};