@stim-cli/core 1.0.0-rc.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,14 @@
+# @stim-cli/core
+
+The primitives [`stim-cli`](https://www.npmjs.com/package/stim-cli),
+[`@stim-cli/metro`](https://www.npmjs.com/package/@stim-cli/metro) and
+[`@stim-cli/expo-build-cache`](https://www.npmjs.com/package/@stim-cli/expo-build-cache)
+must agree on, implemented once: where the stim-cli config dir and the two
+shared caches live (env override > machine config > default), how a build
+cache key is derived, and how a cache registers itself for `stim gc`.
+Metro cache overrides name a parent directory; the sanitized app name is always
+appended beneath it, just as it is beneath the default root.
+
+This is an internal dependency of those packages, not a user-facing API --
+install one of them instead. It is ESM-only and has no dependencies. The
+`module-sync` export lets supported Node versions load it through `require()`.

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+//#region index.d.ts
+interface DirLockOptions {
+  staleMs?: number;
+  waitMs?: number;
+  pollMs?: number;
+  ensureParent?: () => void;
+}
+declare function withDirLock<T>(lockPath: string, fn: () => T, { staleMs, waitMs, pollMs, ensureParent }?: DirLockOptions): T;
+declare function configDir(): string;
+declare function workspaceSlug(projectRoot: string): string;
+declare function workspaceId(projectRoot: string): string;
+declare function workspaceName(projectRoot: string): string;
+declare function workspaceStateDir(projectRoot: string): string;
+declare function workspaceLogDir(projectRoot: string): string;
+declare function cachePathSetting(key: "buildCache" | "metroCache"): string | null;
+declare function cacheNameSegment(name: string | null | undefined): string;
+declare function buildCacheRoot(): string;
+declare function metroCacheRoot(name?: string | null): string;
+declare const STORE_ROOT_TAG = "stimCliStoreRoot";
+declare function tagSharedStore<T extends object>(store: T, root: string): T;
+declare function sharedStoreRoot(store: unknown): string | null;
+interface BuildRunOptions {
+  variant?: string;
+  configuration?: string;
+  buildConfiguration?: string;
+  isSimulator?: boolean;
+  device?: string | boolean | null;
+}
+declare function buildCacheKey(platform: string, fingerprintHash: string, options?: unknown): string;
+interface RegisterOptions {
+  dir: string;
+  name: string;
+  prune: string;
+  note: string;
+  entriesDepth?: number;
+  layout?: string;
+  replaces?: CacheRegistrationMatch[];
+}
+interface CacheRegistrationMatch {
+  dir: string;
+  name?: string;
+  prune?: string;
+  entriesDepth?: number;
+  layout?: string | null;
+}
+declare const METRO_NAMED_CACHE_LAYOUT = "metro-named-v1";
+interface CacheManifest {
+  version: number;
+  caches: Array<Record<string, unknown>>;
+}
+declare function cacheManifestLockPath(file: string): string;
+declare function readCacheManifest(file: string): CacheManifest;
+declare function updateCacheManifest(file: string, mutate: (caches: Array<Record<string, unknown>>) => Array<Record<string, unknown>>): CacheManifest;
+declare function registerCache({ dir, name, prune, note, entriesDepth, layout, replaces }: RegisterOptions): void;
+//#endregion
+export { BuildRunOptions, CacheManifest, CacheRegistrationMatch, DirLockOptions, METRO_NAMED_CACHE_LAYOUT, RegisterOptions, STORE_ROOT_TAG, buildCacheKey, buildCacheRoot, cacheManifestLockPath, cacheNameSegment, cachePathSetting, configDir, metroCacheRoot, readCacheManifest, registerCache, sharedStoreRoot, tagSharedStore, updateCacheManifest, withDirLock, workspaceId, workspaceLogDir, workspaceName, workspaceSlug, workspaceStateDir };

package/dist/index.mjs

@@ -0,0 +1,219 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+//#region index.ts
+const DEFAULT_LOCK_STALE_MS = 1e4;
+const DEFAULT_LOCK_WAIT_MS = 12e3;
+const DEFAULT_LOCK_POLL_MS = 25;
+const lockDepths = /* @__PURE__ */ new Map();
+function sleepSync(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function acquireDirLock(lockPath, { staleMs, waitMs, pollMs, ensureParent }) {
+	ensureParent?.();
+	const deadline = Date.now() + waitMs;
+	for (;;) {
+		try {
+			fs.mkdirSync(lockPath);
+			return;
+		} catch (error) {
+			if (error?.code !== "EEXIST") throw error;
+		}
+		let ageMs = null;
+		try {
+			ageMs = Date.now() - fs.statSync(lockPath).mtimeMs;
+		} catch {
+			continue;
+		}
+		if (ageMs > staleMs) {
+			try {
+				fs.rmSync(lockPath, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+			continue;
+		}
+		if (Date.now() >= deadline) {
+			const error = /* @__PURE__ */ new Error(`Timed out waiting for the lock at ${lockPath}. Another stim-cli process is holding it; if none is running, remove that directory.`);
+			error.code = "STIM_CLI_LOCK_TIMEOUT";
+			error.lockPath = lockPath;
+			throw error;
+		}
+		sleepSync(pollMs);
+	}
+}
+function releaseDirLock(lockPath) {
+	try {
+		fs.rmSync(lockPath, {
+			recursive: true,
+			force: true
+		});
+	} catch {}
+}
+function withDirLock(lockPath, fn, { staleMs = DEFAULT_LOCK_STALE_MS, waitMs = DEFAULT_LOCK_WAIT_MS, pollMs = DEFAULT_LOCK_POLL_MS, ensureParent } = {}) {
+	const depth = lockDepths.get(lockPath) || 0;
+	if (depth > 0) {
+		lockDepths.set(lockPath, depth + 1);
+		try {
+			return fn();
+		} finally {
+			lockDepths.set(lockPath, (lockDepths.get(lockPath) ?? 1) - 1);
+		}
+	}
+	acquireDirLock(lockPath, {
+		staleMs,
+		waitMs,
+		pollMs,
+		ensureParent
+	});
+	lockDepths.set(lockPath, 1);
+	try {
+		return fn();
+	} finally {
+		lockDepths.set(lockPath, 0);
+		releaseDirLock(lockPath);
+	}
+}
+function configDir() {
+	return process.env.STIM_CLI_HOME || path.join(os.homedir(), ".stim-cli");
+}
+function workspaceSlug(projectRoot) {
+	return path.basename(path.resolve(projectRoot)).normalize("NFKD").replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase().slice(0, 48) || "workspace";
+}
+function workspaceId(projectRoot) {
+	return createHash("sha256").update(path.resolve(projectRoot)).digest("hex").slice(0, 16);
+}
+function workspaceName(projectRoot) {
+	return `${workspaceSlug(projectRoot)}--${workspaceId(projectRoot)}`;
+}
+function workspaceStateDir(projectRoot) {
+	return path.join(configDir(), "workspaces", workspaceName(projectRoot));
+}
+function workspaceLogDir(projectRoot) {
+	return path.join(workspaceStateDir(projectRoot), "logs");
+}
+function cachePathSetting(key) {
+	try {
+		const value = JSON.parse(fs.readFileSync(path.join(configDir(), "config.json"), "utf-8"))?.caches?.[key];
+		return typeof value === "string" && value.startsWith("/") ? value : null;
+	} catch {
+		return null;
+	}
+}
+function cacheNameSegment(name) {
+	return String(name).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^\.+/, "") || "app";
+}
+function buildCacheRoot() {
+	return process.env.STIM_CLI_BUILD_CACHE || cachePathSetting("buildCache") || path.join(configDir(), "build-cache");
+}
+function metroCacheRoot(name) {
+	const root = process.env.STIM_CLI_METRO_CACHE || cachePathSetting("metroCache") || path.join(configDir(), "metro-cache");
+	return name === void 0 || name === null || name === "" ? root : path.join(root, cacheNameSegment(name));
+}
+const STORE_ROOT_TAG = "stimCliStoreRoot";
+function tagSharedStore(store, root) {
+	try {
+		Object.defineProperty(store, STORE_ROOT_TAG, {
+			value: root,
+			enumerable: false,
+			configurable: true
+		});
+	} catch {}
+	return store;
+}
+function sharedStoreRoot(store) {
+	if (store === null || typeof store !== "object") return null;
+	const tagged = store[STORE_ROOT_TAG];
+	if (typeof tagged === "string") return tagged;
+	const legacy = store._root;
+	return typeof legacy === "string" ? legacy : null;
+}
+const SIMULATOR_UDID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const EMULATOR_SERIAL = /^emulator-\d+$/;
+function slug(value) {
+	return String(value).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function buildVariant(platform, options) {
+	const raw = platform === "android" ? options.variant : options.configuration ?? options.buildConfiguration;
+	return (typeof raw === "string" ? slug(raw) : "") || "debug";
+}
+function buildTarget(options) {
+	if (typeof options.isSimulator === "boolean") return options.isSimulator ? "sim" : "device";
+	const device = options.device;
+	if (device === void 0 || device === null || device === false) return "sim";
+	if (typeof device !== "string") return "prompted";
+	const name = device.trim();
+	if (name === "" || name === "generic") return "sim";
+	if (SIMULATOR_UDID.test(name) || EMULATOR_SERIAL.test(name)) return "sim";
+	return `on-${slug(name)}`;
+}
+function buildCacheKey(platform, fingerprintHash, options = {}) {
+	const opts = options && typeof options === "object" ? options : {};
+	return `${fingerprintHash}-${buildVariant(platform, opts)}-${buildTarget(opts)}`;
+}
+const METRO_NAMED_CACHE_LAYOUT = "metro-named-v1";
+function cacheManifestLockPath(file) {
+	return `${file}.lock`;
+}
+function readCacheManifest(file) {
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+		return {
+			version: 1,
+			caches: Array.isArray(parsed?.caches) ? parsed.caches : []
+		};
+	} catch {
+		return {
+			version: 1,
+			caches: []
+		};
+	}
+}
+function updateCacheManifest(file, mutate) {
+	const parent = path.dirname(file);
+	return withDirLock(cacheManifestLockPath(file), () => {
+		const next = {
+			version: 1,
+			caches: mutate(readCacheManifest(file).caches)
+		};
+		const temporary = path.join(parent, `.${path.basename(file)}.${process.pid}.tmp`);
+		try {
+			fs.writeFileSync(temporary, JSON.stringify(next, null, 2));
+			fs.renameSync(temporary, file);
+		} catch (error) {
+			fs.rmSync(temporary, { force: true });
+			throw error;
+		}
+		return next;
+	}, { ensureParent: () => fs.mkdirSync(parent, { recursive: true }) });
+}
+function registerCache({ dir, name, prune, note, entriesDepth, layout, replaces = [] }) {
+	try {
+		updateCacheManifest(path.join(configDir(), "caches.json"), (caches) => {
+			const others = caches.filter((cache) => cache.dir !== dir && !replaces.some((match) => matchesCache(cache, match)));
+			const record = {
+				dir,
+				name,
+				prune,
+				note,
+				registeredBy: process.cwd()
+			};
+			if (entriesDepth) record.entriesDepth = entriesDepth;
+			if (layout) record.layout = layout;
+			others.push(record);
+			return others;
+		});
+	} catch {}
+}
+function matchesCache(cache, match) {
+	if (cache.dir !== match.dir) return false;
+	if (match.name !== void 0 && cache.name !== match.name) return false;
+	if (match.prune !== void 0 && cache.prune !== match.prune) return false;
+	if (match.entriesDepth !== void 0 && cache.entriesDepth !== match.entriesDepth) return false;
+	if (match.layout === null) return !Object.hasOwn(cache, "layout");
+	return match.layout === void 0 || cache.layout === match.layout;
+}
+//#endregion
+export { METRO_NAMED_CACHE_LAYOUT, STORE_ROOT_TAG, buildCacheKey, buildCacheRoot, cacheManifestLockPath, cacheNameSegment, cachePathSetting, configDir, metroCacheRoot, readCacheManifest, registerCache, sharedStoreRoot, tagSharedStore, updateCacheManifest, withDirLock, workspaceId, workspaceLogDir, workspaceName, workspaceSlug, workspaceStateDir };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@stim-cli/core",
+  "version": "1.0.0-rc.0",
+  "description": "Shared primitives for stim-cli and its cache packages: config-dir and cache-root resolution, the build cache key, and cache self-registration. Not a user-facing API.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appandflow/stim-cli.git",
+    "directory": "packages/core"
+  },
+  "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"
+    }
+  },
+  "engines": {
+    "node": "^20.19.4 || >=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}