stim 1.0.0 → 1.2.0

package/dist/ownership-claim-7zRxxTfZ.mjs

@@ -0,0 +1,569 @@
+import { E as inspectProcessIdentity, w as captureProcessIdentity } from "./config-CMtIaTk9.mjs";
+import { d as quotedPath } from "./command-output-8wHMEde0.mjs";
+import { lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+//#region src/ownership-claim.ts
+const CLAIM_REFUSED = "STIM_CLAIM_REFUSED";
+const CLAIM_UNAVAILABLE = "STIM_CLAIM_UNAVAILABLE";
+/**
+* The refusal reason for a claim store whose own path is occupied by a file. It names a filesystem
+* state that predates any claim, so a caller that only reads can tell it apart from an unresolvable
+* claim record and fall back to what it did before claims existed.
+*/
+const CLAIM_PATH_NOT_A_DIRECTORY = "the claim path is a file, not a claim directory";
+const EXCLUSIVE_DIR = "exclusive";
+const SHARED_DIR = "shared";
+const CLAIM_SUFFIX = ".claim";
+const CHILD_SUFFIX = ".child";
+const STAGING_PREFIX = ".staging-";
+const PUBLISH_ATTEMPTS = 64;
+var ClaimRefusedError = class extends Error {
+	code = CLAIM_REFUSED;
+	claimPath;
+	reason;
+	removeCommand;
+	constructor({ claimPath, root, reason, label }) {
+		const removeCommand = claimRemoveCommand(claimPath.startsWith(root) ? claimPath : root);
+		super(`Stim cannot tell whether the ${label} claim at ${claimPath} is still held: ${reason}. It will not remove a claim it cannot prove is dead, and it will not wait on one either. If nothing is using it, remove the claim and run the command again:\n  ${removeCommand}`);
+		this.claimPath = claimPath;
+		this.reason = reason;
+		this.removeCommand = removeCommand;
+	}
+};
+var ClaimUnavailableError = class extends Error {
+	code = CLAIM_UNAVAILABLE;
+	reason;
+	constructor(reason) {
+		super(`Stim could not record a process identity, so it cannot take an ownership claim: ${reason}.`);
+		this.reason = reason;
+	}
+};
+/**
+* The command that clears one surveyed claim: targeted at the claim's own file when the path names one,
+* and quoted, because this text is printed for a human to copy into a shell and a path with a space in
+* it would otherwise name several targets.
+*/
+function claimRemoveCommand(path) {
+	return `rm ${path.endsWith(CLAIM_SUFFIX) || path.endsWith(CHILD_SUFFIX) ? "-f" : "-rf"} ${quotedPath(path)}`;
+}
+function isClaimRefusal(err) {
+	return err?.code === CLAIM_REFUSED;
+}
+function isClaimUnavailable(err) {
+	return err?.code === CLAIM_UNAVAILABLE;
+}
+/**
+* The refusal a command reports for either error the claim primitive raises, and null for anything else.
+* Both are refusals: a claim Stim cannot resolve and a process identity it cannot record are the two
+* states in which it holds no claim, and running the operation a claim serializes without one gives a
+* competing run no protection at all.
+*/
+function claimFailure(err, retryCommand) {
+	if (isClaimRefusal(err)) return {
+		code: CLAIM_REFUSED,
+		message: err.message,
+		remedy: `Run \`${err.removeCommand}\`, then run \`${retryCommand}\` again.`
+	};
+	if (isClaimUnavailable(err)) return {
+		code: CLAIM_UNAVAILABLE,
+		message: err.message,
+		remedy: `Reinstall Stim so the unique-pid native module for this platform is present, then run \`${retryCommand}\` again.`
+	};
+	return null;
+}
+function exclusiveClaimDir(root) {
+	return join(root, EXCLUSIVE_DIR);
+}
+function sharedClaimDir(root) {
+	return join(root, SHARED_DIR);
+}
+function childPath(claimPath) {
+	return `${claimPath.slice(0, -6)}${CHILD_SUFFIX}`;
+}
+function asOwner(record) {
+	const candidate = record;
+	if (!candidate || typeof candidate !== "object") return null;
+	if (typeof candidate.pid !== "number" || !Number.isSafeInteger(candidate.pid) || candidate.pid <= 0) return null;
+	if (typeof candidate.processToken !== "string" || !candidate.processToken) return null;
+	return {
+		pid: candidate.pid,
+		processToken: candidate.processToken
+	};
+}
+function readChild(claimPath) {
+	let text;
+	try {
+		text = readFileSync(childPath(claimPath), "utf-8");
+	} catch (err) {
+		if (err?.code === "ENOENT") return null;
+		return "unreadable";
+	}
+	try {
+		return { record: asOwner(JSON.parse(text)?.record) };
+	} catch {
+		return "unreadable";
+	}
+}
+function readClaim(path, mode) {
+	let text;
+	try {
+		text = readFileSync(path, "utf-8");
+	} catch (err) {
+		if (err?.code === "ENOENT") return null;
+		return "unreadable";
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return "unreadable";
+	}
+	const owner = asOwner(parsed?.owner);
+	if (!owner || typeof parsed.claimId !== "string" || !parsed.claimId) return "unreadable";
+	const child = readChild(path);
+	if (child === "unreadable") return "unreadable";
+	return {
+		path,
+		claimId: parsed.claimId,
+		mode,
+		owner,
+		startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : "",
+		details: parsed.details && typeof parsed.details === "object" ? parsed.details : {},
+		child: child?.record ?? null,
+		childDeclared: child !== null
+	};
+}
+/**
+* Whether any member of the process group `pid` leads is alive. A recorded child is resolved through
+* its group rather than through the one process, so a package manager's postinstall descendant keeps
+* the claim after the manager exits. A pgid, unlike a ProcessRecord, carries no identity: a recycled
+* one reads as alive, which holds a claim longer than it needs to be held and never frees a live one.
+*/
+function processGroupAlive(pid) {
+	if (!Number.isSafeInteger(pid) || pid <= 1) return false;
+	try {
+		process.kill(-pid, 0);
+		return true;
+	} catch (err) {
+		return err?.code === "EPERM";
+	}
+}
+function childLiveness(claimPath) {
+	const child = readChild(claimPath);
+	if (child === null) return "none";
+	if (child === "unreadable" || !child.record) return "unknown";
+	const status = inspectProcessIdentity(child.record);
+	if (status === "same") return "live";
+	if (status === "gone") return processGroupAlive(child.record.pid) ? "live" : "dead";
+	return "unknown";
+}
+function claimLiveness(holder) {
+	const status = inspectProcessIdentity(holder.owner);
+	if (status === "same") return "live";
+	if (status === "unknown") return "unknown";
+	const child = childLiveness(holder.path);
+	return child === "none" ? "dead" : child;
+}
+function refuse(root, claimPath, label, reason) {
+	throw new ClaimRefusedError({
+		claimPath,
+		root,
+		label,
+		reason
+	});
+}
+function names(dir) {
+	try {
+		return readdirSync(dir).toSorted();
+	} catch (err) {
+		if (err?.code === "ENOENT") return [];
+		return "unreadable";
+	}
+}
+function survey(dir, mode, into) {
+	const listed = names(dir);
+	if (listed === "unreadable") {
+		into.unresolved.push({
+			path: dir,
+			reason: "its directory could not be read"
+		});
+		return;
+	}
+	const claims = new Set(listed.filter((name) => name.endsWith(CLAIM_SUFFIX)));
+	const orphans = listed.filter((name) => name.endsWith(CHILD_SUFFIX) && !claims.has(`${name.slice(0, -6)}${CLAIM_SUFFIX}`));
+	for (const name of orphans) into.orphans.push(join(dir, name));
+	for (const name of listed) {
+		if (!name.endsWith(CLAIM_SUFFIX)) continue;
+		const path = join(dir, name);
+		const holder = readClaim(path, mode);
+		if (holder === null) continue;
+		if (holder === "unreadable") {
+			into.unresolved.push({
+				path,
+				reason: "its record is missing, truncated or not valid JSON"
+			});
+			continue;
+		}
+		const liveness = claimLiveness(holder);
+		if (liveness === "live") into.live.push(holder);
+		else if (liveness === "dead") into.dead.push(holder);
+		else into.unresolved.push({
+			path,
+			reason: holder.childDeclared && !holder.child ? "it spawned the process that holds it and was killed before recording which one" : "its process identity token does not decode, so the holder cannot be identified"
+		});
+	}
+	if (listed.filter((name) => !orphans.includes(name)).length > 0 && claims.size === 0) into.unresolved.push({
+		path: dir,
+		reason: "it holds files Stim did not write"
+	});
+}
+/** Classify every claim in a claim set without removing anything and without refusing. */
+function readClaimSet(root) {
+	const state = {
+		live: [],
+		dead: [],
+		unresolved: [],
+		orphans: []
+	};
+	survey(exclusiveClaimDir(root), "exclusive", state);
+	survey(sharedClaimDir(root), "shared", state);
+	return state;
+}
+function removeOrRefuse(path, root, claimPath, label) {
+	try {
+		unlinkSync(path);
+	} catch (err) {
+		const code = err?.code;
+		if (code === "ENOENT") return;
+		refuse(root, claimPath, label, `the claim left behind could not be removed (${code || err?.message})`);
+	}
+}
+function reap(holder, root, label) {
+	const again = readClaim(holder.path, holder.mode);
+	if (again === null) return true;
+	if (again === "unreadable" || again.claimId !== holder.claimId) return false;
+	removeOrRefuse(childPath(holder.path), root, holder.path, label);
+	removeOrRefuse(holder.path, root, holder.path, label);
+	return true;
+}
+function tidy(dir) {
+	try {
+		rmdirSync(dir);
+	} catch {}
+}
+function inspectClaimSet(root, { label = "ownership" } = {}) {
+	const state = readClaimSet(root);
+	const unresolved = state.unresolved[0];
+	if (unresolved) refuse(root, unresolved.path, label, unresolved.reason);
+	const reaped = [];
+	for (const orphan of state.orphans) removeOrRefuse(orphan, root, orphan, label);
+	for (const holder of state.dead) if (reap(holder, root, label)) reaped.push(holder);
+	if (!state.live.some((holder) => holder.mode === "exclusive")) tidy(exclusiveClaimDir(root));
+	if (!state.live.some((holder) => holder.mode === "shared")) tidy(sharedClaimDir(root));
+	return {
+		exclusive: state.live.find((holder) => holder.mode === "exclusive") ?? null,
+		shared: state.live.filter((holder) => holder.mode === "shared"),
+		reaped
+	};
+}
+function tidySet(root) {
+	tidy(exclusiveClaimDir(root));
+	tidy(sharedClaimDir(root));
+	tidy(root);
+}
+function removeAbandonedStaging(root) {
+	const listed = names(root);
+	if (listed === "unreadable") return;
+	for (const name of listed) if (name.startsWith(STAGING_PREFIX)) rmSync(join(root, name), {
+		recursive: true,
+		force: true
+	});
+}
+/**
+* Remove a claim set that holds nothing. Takes the set's own exclusive claim first and removes the set
+* only through the token-verified unlink and empty-directory removals that releasing a claim performs,
+* so a claim published between the survey that reported the set stale and this call is kept, not
+* deleted; a set whose state cannot be established is refused rather than removed.
+*/
+function clearFreeClaimSet({ root, label = "ownership" }) {
+	let attempt;
+	try {
+		attempt = tryAcquireClaim({
+			root,
+			mode: "exclusive",
+			label
+		});
+	} catch (err) {
+		if (isClaimRefusal(err) || isClaimUnavailable(err)) return {
+			status: "refused",
+			reason: err.reason
+		};
+		return {
+			status: "failed",
+			reason: err?.message ?? String(err)
+		};
+	}
+	if (!attempt.acquired) {
+		if (attempt.pending) releaseClaim(attempt.pending);
+		return {
+			status: "held",
+			holder: attempt.held ?? attempt.waitingFor?.[0] ?? null
+		};
+	}
+	try {
+		removeAbandonedStaging(root);
+	} catch (err) {
+		return {
+			status: "failed",
+			reason: err?.message ?? String(err)
+		};
+	} finally {
+		releaseClaim(attempt.acquired);
+	}
+	tidySet(root);
+	const remaining = names(root);
+	if (remaining === "unreadable") return {
+		status: "failed",
+		reason: "its directory could not be read"
+	};
+	const after = readClaimSet(root);
+	if (after.live.length > 0) return {
+		status: "held",
+		holder: after.live[0]
+	};
+	if (after.unresolved.length > 0) return {
+		status: "refused",
+		reason: after.unresolved[0].reason
+	};
+	if (remaining.length > 0) return {
+		status: "failed",
+		reason: `it still holds ${remaining.join(", ")}`
+	};
+	return { status: "cleared" };
+}
+function selfOwner() {
+	const captured = captureProcessIdentity(process.pid);
+	if (!captured.ok) throw new ClaimUnavailableError(captured.reason);
+	return {
+		pid: process.pid,
+		processToken: captured.token
+	};
+}
+function contended(error) {
+	if (error instanceof MissingClaimStoreError) return false;
+	const code = error?.code;
+	return code === "EEXIST" || code === "ENOTEMPTY" || code === "ENOENT" || code === "EINVAL";
+}
+var MissingClaimStoreError = class extends Error {
+	code = "ENOENT";
+};
+function createClaimDir(path) {
+	try {
+		mkdirSync(path, { recursive: true });
+		return;
+	} catch (error) {
+		if (error?.code !== "ENOENT") throw error;
+	}
+	const missing = [];
+	for (let level = path;; level = dirname(level)) {
+		let entry;
+		try {
+			entry = lstatSync(level);
+		} catch (error) {
+			if (error?.code !== "ENOENT") throw error;
+			missing.push(level);
+			continue;
+		}
+		if (entry.isSymbolicLink()) try {
+			statSync(level);
+		} catch (error) {
+			if (error?.code === "ENOENT") throw new MissingClaimStoreError(error.message, { cause: error });
+			throw error;
+		}
+		break;
+	}
+	for (const level of missing.toReversed()) try {
+		mkdirSync(level);
+	} catch (error) {
+		if (error?.code !== "EEXIST") throw error;
+	}
+}
+function publishExclusive(root, payload, claimId, label) {
+	const staging = join(root, `${STAGING_PREFIX}${claimId}`);
+	const target = exclusiveClaimDir(root);
+	try {
+		createClaimDir(staging);
+		writeFileSync(join(staging, `${claimId}${CLAIM_SUFFIX}`), payload);
+		renameSync(staging, target);
+		return join(target, `${claimId}${CLAIM_SUFFIX}`);
+	} catch (err) {
+		rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+		const code = err?.code;
+		if (contended(err)) return null;
+		if (code === "ENOTDIR") refuse(root, target, label, CLAIM_PATH_NOT_A_DIRECTORY);
+		throw err;
+	}
+}
+function publishShared(root, payload, claimId) {
+	const staging = join(root, `${STAGING_PREFIX}${claimId}`);
+	const target = join(sharedClaimDir(root), `${claimId}${CLAIM_SUFFIX}`);
+	try {
+		createClaimDir(sharedClaimDir(root));
+		writeFileSync(staging, payload);
+		renameSync(staging, target);
+		return target;
+	} catch (err) {
+		rmSync(staging, { force: true });
+		if (contended(err)) return null;
+		throw err;
+	}
+}
+function settleOrRelease(claim) {
+	try {
+		return inspectClaimSet(claim.root, { label: claim.label });
+	} catch (err) {
+		releaseClaim(claim);
+		throw err;
+	}
+}
+function tryAcquireClaim({ root, mode, details = {}, label = "ownership" }) {
+	const owner = selfOwner();
+	const reaped = [];
+	for (let attempt = 0; attempt < PUBLISH_ATTEMPTS; attempt++) {
+		try {
+			createClaimDir(root);
+		} catch (err) {
+			const code = err?.code;
+			if (code === "EEXIST" || code === "ENOTDIR") refuse(root, root, label, CLAIM_PATH_NOT_A_DIRECTORY);
+			if (contended(err)) continue;
+			throw err;
+		}
+		const state = inspectClaimSet(root, { label });
+		reaped.push(...state.reaped);
+		if (state.exclusive) return {
+			held: state.exclusive,
+			reaped
+		};
+		const claimId = randomUUID();
+		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const payload = JSON.stringify({
+			claimId,
+			mode,
+			owner,
+			startedAt,
+			details
+		});
+		const handle = (path) => ({
+			root,
+			path,
+			claimId,
+			mode,
+			owner,
+			startedAt,
+			details,
+			label
+		});
+		if (mode === "shared") {
+			const published = publishShared(root, payload, claimId);
+			if (!published) continue;
+			const claim = handle(published);
+			const settled = settleOrRelease(claim);
+			reaped.push(...settled.reaped);
+			if (!settled.exclusive) return {
+				acquired: claim,
+				reaped
+			};
+			releaseClaim(claim);
+			return {
+				held: settled.exclusive,
+				reaped
+			};
+		}
+		const path = publishExclusive(root, payload, claimId, label);
+		if (!path) continue;
+		const claim = handle(path);
+		const settled = settleOrRelease(claim);
+		reaped.push(...settled.reaped);
+		if (settled.shared.length === 0) return {
+			acquired: claim,
+			reaped
+		};
+		return {
+			waitingFor: settled.shared,
+			pending: claim,
+			reaped
+		};
+	}
+	const contender = inspectClaimSet(root, { label });
+	reaped.push(...contender.reaped);
+	const holder = contender.exclusive ?? (mode === "exclusive" ? contender.shared[0] : void 0);
+	if (holder) return {
+		held: holder,
+		reaped
+	};
+	refuse(root, root, label, `another process took and gave up the claim on every one of ${PUBLISH_ATTEMPTS} attempts to take it`);
+}
+function settleClaim(pending) {
+	const state = inspectClaimSet(pending.root, { label: pending.label });
+	if (state.shared.length === 0) return {
+		acquired: pending,
+		reaped: state.reaped
+	};
+	return {
+		waitingFor: state.shared,
+		pending,
+		reaped: state.reaped
+	};
+}
+function releaseClaim(handle) {
+	if (!handle) return false;
+	const current = readClaim(handle.path, handle.mode);
+	if (current === null) return true;
+	if (current === "unreadable" || current.claimId !== handle.claimId) return false;
+	try {
+		rmSync(childPath(handle.path), { force: true });
+		rmSync(handle.path, { force: true });
+	} catch {
+		return false;
+	}
+	tidy(handle.mode === "exclusive" ? exclusiveClaimDir(handle.root) : sharedClaimDir(handle.root));
+	tidy(handle.root);
+	return true;
+}
+/**
+* Declare that this claim is about to spawn the process that does the real work, before the spawn.
+* A claim marked this way and left without a child record reads as unresolvable rather than as free,
+* so a parent killed between the spawn and the record cannot release a claim its child still needs.
+*/
+function markClaimChildPending(handle) {
+	writeChild(handle, { record: null });
+}
+/**
+* Record the spawned process that holds this claim. Spawn it with `detached: true` so it leads its own
+* process group: the claim then reads as held while any member of that group is alive, which is what
+* keeps a package manager's postinstall child covered after the manager itself exits.
+*/
+function setClaimChild(handle, record) {
+	const child = asOwner(record);
+	if (!child) throw new ClaimUnavailableError("the child process identity was not a pid and token pair");
+	writeChild(handle, { record: child });
+}
+function clearClaimChild(handle) {
+	rmSync(childPath(handle.path), { force: true });
+}
+function writeChild(handle, body) {
+	const staging = join(handle.root, `${STAGING_PREFIX}child-${handle.claimId}`);
+	try {
+		writeFileSync(staging, JSON.stringify(body));
+		renameSync(staging, childPath(handle.path));
+	} catch (err) {
+		rmSync(staging, { force: true });
+		throw err;
+	}
+}
+//#endregion
+export { clearClaimChild as a, isClaimUnavailable as c, readClaimSet as d, releaseClaim as f, tryAcquireClaim as h, claimRemoveCommand as i, markClaimChildPending as l, settleClaim as m, ClaimRefusedError as n, clearFreeClaimSet as o, setClaimChild as p, claimFailure as r, isClaimRefusal as s, CLAIM_PATH_NOT_A_DIRECTORY as t, processGroupAlive as u };

package/dist/{project-Dit1CckW.mjs → project-BBTVABUz.mjs}

@@ -1,7 +1,8 @@
-import { s as findEnclosingWorktreeRoot, u as getProject } from "./config-7kmtuhO2.mjs";
+import { c as findEnclosingWorktreeRoot, f as getProject } from "./config-CMtIaTk9.mjs";
+import { g as repoRoot } from "./worktree-C79xx_kM.mjs";
 import { existsSync, readFileSync, readdirSync, realpathSync } from "fs";
+import { basename, dirname, join, resolve } from "path";
 import { createRequire } from "module";
-import { dirname, join, resolve } from "path";
 //#region src/project.ts
 const requireFromHere = createRequire(import.meta.url);
 function resolvePackageJson(projectRoot, name) {
@@ -29,6 +30,14 @@ function projectShortcut(path, proj) {
 	if (rootPath && rootPath !== path) return `${projectShortcut(rootPath, getProject(rootPath))}/${path.split("/").pop() || path}`;
 	return path.split("/").pop() || path;
 }
+function ownedDeviceLabel(projectPath) {
+	const app = realpathSync(projectPath);
+	const root = repoRoot(app);
+	const appLabel = basename(app);
+	if (!root) return appLabel;
+	const worktreeLabel = basename(realpathSync(root));
+	return worktreeLabel === appLabel ? appLabel : `${worktreeLabel}-${appLabel}`;
+}
 function findProjectRoot(startDir) {
 	let dir;
 	try {
@@ -231,4 +240,4 @@ function detectAndroidPackageFromGradle(projectRoot) {
 	return null;
 }
 //#endregion
-export { findProjectRoot as a, resolvePackageJson as c, detectIsExpo as i, detectAndroidPackage as n, isPackageResolvable as o, detectBundleId as r, projectShortcut as s, appProjectProblem as t };
+export { findProjectRoot as a, projectShortcut as c, detectIsExpo as i, resolvePackageJson as l, detectAndroidPackage as n, isPackageResolvable as o, detectBundleId as r, ownedDeviceLabel as s, appProjectProblem as t };