@stim-cli/core 1.20.1 → 1.21.0

package/dist/toolchain.d.mts

@@ -0,0 +1,64 @@
+//#region toolchain.d.ts
+/** How `discoverToolchain` and `projectNodeBin` look at this machine; tests pass a fake file system. */
+interface ToolchainProbe {
+  home: string;
+  /** The running Node, whose directory is the last `PATH` entry so `node` always resolves. */
+  execPath: string;
+  isDir(path: string): boolean;
+  isFile(path: string): boolean;
+  read(path: string): string | null;
+  list(path: string): string[];
+}
+declare function defaultToolchainProbe(): ToolchainProbe;
+/**
+ * One toolchain fact for `stim doctor`: `source` is `environment` when the caller's environment already set it,
+ * `discovered` when `discoverToolchain` found it at `from`, and `missing` when neither did. A discovered
+ * `JAVA_HOME` for a system JDK is reported but not set, since `/usr/bin/java` already finds it.
+ */
+interface ToolchainEntry {
+  name: string;
+  value: string | null;
+  source: "environment" | "discovered" | "missing";
+  from?: string;
+}
+interface Toolchain {
+  env: Record<string, string>;
+  entries: ToolchainEntry[];
+}
+/** Whether Node `version`, such as `22.12.0`, satisfies a pin such as `22`, `v22.12` or `22.12.0`. */
+declare function satisfiesNodePin(version: string, spec: string): boolean;
+/** The `bin` directory of the Node a version manager makes the default in new shells, and where that came from. */
+declare function defaultNodeBin(env: NodeJS.ProcessEnv, probe: ToolchainProbe): {
+  bin: string;
+  from: string;
+} | null;
+/**
+ * The toolchain environment a process started outside a login shell, such as stim-server under Stim Desktop or
+ * launchd, needs: `base` with Homebrew, `~/.local/bin`, the default Node's directory and the Android SDK tools
+ * appended to `PATH`, and `ANDROID_HOME` and `JAVA_HOME` set when `base` lacks them and they can be found. It only
+ * fills gaps: nothing `base` sets is replaced, and every added `PATH` entry goes after the existing ones. Unless
+ * `runningNode` is false, the running Node's directory is always the last entry, so `node` resolves. `PNPM_HOME` is
+ * set to pnpm's global directory when that is added, since pnpm's global commands need it.
+ */
+declare function discoverToolchain(base: NodeJS.ProcessEnv, probe?: ToolchainProbe, { runningNode, platform }?: {
+  runningNode?: boolean;
+  platform?: NodeJS.Platform;
+}): Toolchain;
+/** The Node version `root` pins, from `.nvmrc`, `.node-version`, `.tool-versions` or `package.json`'s `volta.node`. */
+declare function projectNodePin(root: string, probe?: ToolchainProbe): {
+  spec: string;
+  file: string;
+} | null;
+/**
+ * The `bin` directory of an installed Node that satisfies `root`'s pin, from nvm, fnm, Volta, asdf or mise, or
+ * nil when the project pins none or no installed version satisfies the pin. An `lts/...` pin resolves through
+ * nvm's aliases.
+ */
+declare function projectNodeBin(root: string, env: NodeJS.ProcessEnv, probe?: ToolchainProbe): {
+  bin: string;
+  version: string;
+  pin: string;
+  spec: string;
+} | null;
+//#endregion
+export { Toolchain, ToolchainEntry, ToolchainProbe, defaultNodeBin, defaultToolchainProbe, discoverToolchain, projectNodeBin, projectNodePin, satisfiesNodePin };

package/dist/toolchain.mjs

@@ -0,0 +1,326 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+//#region toolchain.ts
+const stat = (path) => statSync(path, { throwIfNoEntry: false });
+function defaultToolchainProbe() {
+	return {
+		home: homedir(),
+		execPath: process.execPath,
+		isDir: (path) => stat(path)?.isDirectory() ?? false,
+		isFile: (path) => stat(path)?.isFile() ?? false,
+		read: (path) => {
+			try {
+				return readFileSync(path, "utf8");
+			} catch {
+				return null;
+			}
+		},
+		list: (path) => {
+			try {
+				return readdirSync(path);
+			} catch {
+				return [];
+			}
+		}
+	};
+}
+const HOMEBREW_BINS = [
+	"/opt/homebrew/bin",
+	"/opt/homebrew/sbin",
+	"/usr/local/bin"
+];
+const SYSTEM_JDKS = "/Library/Java/JavaVirtualMachines";
+const HOMEBREW_PREFIXES = ["/opt/homebrew", "/usr/local"];
+/** Homebrew JDKs in the order Android builds prefer them: 17, then 21, then the rest from newest. */
+function jdkRank(name) {
+	const major = Number(/@(\d+)$/.exec(name)?.[1] ?? 1e3);
+	return major === 17 ? 0 : major === 21 ? 1 : 1e4 - major;
+}
+const ANDROID_STUDIOS = ["/Applications/Android Studio.app", "/Applications/Android Studio Preview.app"];
+function parseVersion(text) {
+	const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(text.trim());
+	return match ? [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	] : null;
+}
+function compareVersions(a, b) {
+	return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+/** The newest installed version, of `names` such as `v22.12.0` or `22.12.0`, that `wanted` names. */
+function newestMatching(names, wanted) {
+	const spec = wanted.trim().replace(/^v/, "");
+	const exact = parseVersion(spec);
+	let best = null;
+	for (const name of names) {
+		const version = parseVersion(name);
+		if (!version) continue;
+		if (exact ? compareVersions(version, exact) !== 0 : !matchesPrefix(version, spec)) continue;
+		if (!best || compareVersions(version, best.version) > 0) best = {
+			name,
+			version
+		};
+	}
+	return best?.name ?? null;
+}
+/** Whether Node `version`, such as `22.12.0`, satisfies a pin such as `22`, `v22.12` or `22.12.0`. */
+function satisfiesNodePin(version, spec) {
+	return newestMatching([version], spec) !== null;
+}
+function matchesPrefix(version, spec) {
+	if (spec === "" || spec === "node" || spec === "stable") return true;
+	const parts = spec.split(".");
+	if (parts.length > 3 || parts.some((part) => !/^\d+$/.test(part))) return false;
+	return parts.every((part, index) => Number(part) === version[index]);
+}
+/** nvm's `alias/<name>` chain, which can name another alias such as `lts/*`, down to a version spec. */
+function nvmAlias(nvm, name, probe) {
+	let spec = name;
+	for (let hops = 0; hops < 8; hops++) {
+		const next = probe.read(join(nvm, "alias", spec))?.trim();
+		if (!next) return spec;
+		spec = next;
+	}
+	return spec;
+}
+function nvmDir(env, probe) {
+	return env.NVM_DIR || join(probe.home, ".nvm");
+}
+/** The `bin` directory of the Node a version manager makes the default in new shells, and where that came from. */
+function defaultNodeBin(env, probe) {
+	const nvm = nvmDir(env, probe);
+	if (probe.isFile(join(nvm, "alias", "default"))) {
+		const spec = nvmAlias(nvm, "default", probe);
+		const version = newestMatching(probe.list(join(nvm, "versions", "node")), spec);
+		if (version) return {
+			bin: join(nvm, "versions", "node", version, "bin"),
+			from: `nvm default (${spec})`
+		};
+	}
+	return [
+		{
+			bin: join(probe.home, ".local", "share", "fnm", "aliases", "default", "bin"),
+			from: "fnm default"
+		},
+		{
+			bin: join(probe.home, "Library", "Application Support", "fnm", "aliases", "default", "bin"),
+			from: "fnm default"
+		},
+		{
+			bin: join(probe.home, ".volta", "bin"),
+			from: "Volta"
+		},
+		{
+			bin: join(probe.home, ".local", "share", "mise", "shims"),
+			from: "mise shims"
+		},
+		{
+			bin: join(env.ASDF_DATA_DIR || join(probe.home, ".asdf"), "shims"),
+			from: "asdf shims"
+		}
+	].find(({ bin }) => probe.isFile(join(bin, "node"))) ?? null;
+}
+function pathEntries(path) {
+	return (path ?? "").split(delimiter).filter(Boolean);
+}
+/**
+* The toolchain environment a process started outside a login shell, such as stim-server under Stim Desktop or
+* launchd, needs: `base` with Homebrew, `~/.local/bin`, the default Node's directory and the Android SDK tools
+* appended to `PATH`, and `ANDROID_HOME` and `JAVA_HOME` set when `base` lacks them and they can be found. It only
+* fills gaps: nothing `base` sets is replaced, and every added `PATH` entry goes after the existing ones. Unless
+* `runningNode` is false, the running Node's directory is always the last entry, so `node` resolves. `PNPM_HOME` is
+* set to pnpm's global directory when that is added, since pnpm's global commands need it.
+*/
+function discoverToolchain(base, probe = defaultToolchainProbe(), { runningNode = true, platform = process.platform } = {}) {
+	const env = {};
+	for (const [key, value] of Object.entries(base)) if (value !== void 0) env[platform === "win32" && /^path$/i.test(key) ? "PATH" : key] = value;
+	const entries = [];
+	const path = pathEntries(env.PATH);
+	const append = (dir) => {
+		if (!path.includes(dir) && probe.isDir(dir)) path.push(dir);
+	};
+	const onPath = (name) => path.find((dir) => probe.isFile(join(dir, name))) ?? null;
+	const nodeBefore = onPath("node");
+	const defaultNode = nodeBefore ? null : defaultNodeBin(env, probe);
+	if (defaultNode) append(defaultNode.bin);
+	for (const dir of HOMEBREW_BINS) append(dir);
+	for (const dir of [
+		".local/bin",
+		"Library/pnpm",
+		".bun/bin"
+	]) append(join(probe.home, dir));
+	const pnpmHome = join(probe.home, "Library", "pnpm");
+	if (!env.PNPM_HOME && path.includes(pnpmHome)) env.PNPM_HOME = pnpmHome;
+	const sdkSet = env.ANDROID_HOME || env.ANDROID_SDK_ROOT;
+	const standardSdk = join(probe.home, "Library", "Android", "sdk");
+	const sdk = sdkSet || (probe.isDir(standardSdk) ? standardSdk : null);
+	if (sdk && !sdkSet) env.ANDROID_HOME = sdk;
+	if (sdk) for (const tools of ["platform-tools", "emulator"]) append(join(sdk, tools));
+	entries.push(sdkSet ? {
+		name: "ANDROID_HOME",
+		value: sdkSet,
+		source: "environment"
+	} : sdk ? {
+		name: "ANDROID_HOME",
+		value: sdk,
+		source: "discovered",
+		from: "the Android Studio default location"
+	} : {
+		name: "ANDROID_HOME",
+		value: null,
+		source: "missing"
+	});
+	entries.push(javaEntry(env, probe));
+	const running = dirname(probe.execPath);
+	if (runningNode) append(running);
+	env.PATH = path.join(delimiter);
+	const node = onPath("node");
+	const nodeFrom = nodeBefore ? null : defaultNode && node === defaultNode.bin ? defaultNode.from : node === running ? "the Node running Stim" : node && `${node} on the discovered PATH`;
+	entries.unshift({
+		name: "node",
+		value: node && join(node, "node"),
+		source: nodeBefore ? "environment" : "discovered",
+		...nodeFrom ? { from: nodeFrom } : {}
+	});
+	for (const tool of [
+		"stim",
+		"brew",
+		"adb"
+	]) {
+		const dir = onPath(tool);
+		entries.push(dir ? {
+			name: tool,
+			value: join(dir, tool),
+			source: pathEntries(base.PATH).includes(dir) ? "environment" : "discovered"
+		} : {
+			name: tool,
+			value: null,
+			source: "missing"
+		});
+	}
+	return {
+		env,
+		entries
+	};
+}
+/**
+* `JAVA_HOME` for Gradle. A JDK under /Library/Java/JavaVirtualMachines needs none, because `/usr/bin/java` finds
+* it. Without one, a Homebrew `openjdk`, which /usr/bin/java does not find, is set (17, then 21, then the newest),
+* else Android Studio's bundled runtime.
+*/
+function javaEntry(env, probe) {
+	if (env.JAVA_HOME) return {
+		name: "JAVA_HOME",
+		value: env.JAVA_HOME,
+		source: "environment"
+	};
+	const system = probe.list(SYSTEM_JDKS).map((name) => join(SYSTEM_JDKS, name, "Contents", "Home")).find((home) => probe.isFile(join(home, "bin", "java")));
+	if (system) return {
+		name: "JAVA_HOME",
+		value: system,
+		source: "discovered",
+		from: "a system JDK, which /usr/bin/java runs"
+	};
+	const brewed = HOMEBREW_PREFIXES.flatMap((prefix) => probe.list(join(prefix, "opt")).filter((name) => /^openjdk(@\d+)?$/.test(name)).map((name) => ({
+		name,
+		home: join(prefix, "opt", name, "libexec", "openjdk.jdk", "Contents", "Home")
+	}))).filter(({ home }) => probe.isFile(join(home, "bin", "java"))).toSorted((a, b) => jdkRank(a.name) - jdkRank(b.name))[0];
+	if (brewed) {
+		env.JAVA_HOME = brewed.home;
+		return {
+			name: "JAVA_HOME",
+			value: brewed.home,
+			source: "discovered",
+			from: `Homebrew ${brewed.name}`
+		};
+	}
+	for (const studio of ANDROID_STUDIOS) {
+		const jbr = join(studio, "Contents", "jbr", "Contents", "Home");
+		if (probe.isFile(join(jbr, "bin", "java"))) {
+			env.JAVA_HOME = jbr;
+			return {
+				name: "JAVA_HOME",
+				value: jbr,
+				source: "discovered",
+				from: "Android Studio's bundled runtime"
+			};
+		}
+	}
+	return {
+		name: "JAVA_HOME",
+		value: null,
+		source: "missing"
+	};
+}
+/** The Node version `root` pins, from `.nvmrc`, `.node-version`, `.tool-versions` or `package.json`'s `volta.node`. */
+function projectNodePin(root, probe = defaultToolchainProbe()) {
+	for (const file of [".nvmrc", ".node-version"]) {
+		const line = probe.read(join(root, file))?.split("\n").map((text) => text.trim()).find((text) => text && !text.startsWith("#"));
+		if (line) return {
+			spec: line,
+			file
+		};
+	}
+	const tools = probe.read(join(root, ".tool-versions"));
+	const asdf = tools && /^nodejs\s+(\S+)/m.exec(tools)?.[1];
+	if (asdf) return {
+		spec: asdf,
+		file: ".tool-versions"
+	};
+	const volta = /"volta"\s*:\s*\{[^}]*"node"\s*:\s*"([^"]+)"/.exec(probe.read(join(root, "package.json")) ?? "")?.[1];
+	return volta ? {
+		spec: volta,
+		file: "package.json"
+	} : null;
+}
+/**
+* The `bin` directory of an installed Node that satisfies `root`'s pin, from nvm, fnm, Volta, asdf or mise, or
+* nil when the project pins none or no installed version satisfies the pin. An `lts/...` pin resolves through
+* nvm's aliases.
+*/
+function projectNodeBin(root, env, probe = defaultToolchainProbe()) {
+	const pin = projectNodePin(root, probe);
+	if (!pin) return null;
+	const nvm = nvmDir(env, probe);
+	const spec = pin.spec.startsWith("lts/") ? nvmAlias(nvm, pin.spec, probe) : pin.spec;
+	const stores = [
+		{
+			dir: join(nvm, "versions", "node"),
+			bin: (name) => join(nvm, "versions", "node", name, "bin")
+		},
+		{
+			dir: join(probe.home, ".local", "share", "fnm", "node-versions"),
+			bin: (name) => join(probe.home, ".local", "share", "fnm", "node-versions", name, "installation", "bin")
+		},
+		{
+			dir: join(probe.home, "Library", "Application Support", "fnm", "node-versions"),
+			bin: (name) => join(probe.home, "Library", "Application Support", "fnm", "node-versions", name, "installation", "bin")
+		},
+		{
+			dir: join(probe.home, ".volta", "tools", "image", "node"),
+			bin: (name) => join(probe.home, ".volta", "tools", "image", "node", name, "bin")
+		},
+		{
+			dir: join(env.ASDF_DATA_DIR || join(probe.home, ".asdf"), "installs", "nodejs"),
+			bin: (name) => join(env.ASDF_DATA_DIR || join(probe.home, ".asdf"), "installs", "nodejs", name, "bin")
+		},
+		{
+			dir: join(probe.home, ".local", "share", "mise", "installs", "node"),
+			bin: (name) => join(probe.home, ".local", "share", "mise", "installs", "node", name, "bin")
+		}
+	];
+	for (const store of stores) {
+		const name = newestMatching(probe.list(store.dir), spec);
+		if (name && probe.isFile(join(store.bin(name), "node"))) return {
+			bin: store.bin(name),
+			version: name.replace(/^v/, ""),
+			pin: pin.file,
+			spec
+		};
+	}
+	return null;
+}
+//#endregion
+export { defaultNodeBin, defaultToolchainProbe, discoverToolchain, projectNodeBin, projectNodePin, satisfiesNodePin };

package/dist/workspace-link.d.mts

@@ -0,0 +1,16 @@
+//#region workspace-link.d.ts
+declare const WORKSPACE_LINK_ORIGIN = "https://stim.appandflow.com";
+/** A navigation destination on one Stim home, resolved only through an already-paired server. */
+interface SharedWorkspaceLink {
+  machine: string;
+  workspace: string;
+  platform?: "ios" | "android" | "macos" | "web";
+  slot?: string;
+}
+declare function validHomeId(value: unknown): value is string;
+/** Parses a v1 HTTPS workspace link; unsupported origins, destinations and ambiguous query fields return null. */
+declare function parseWorkspaceLink(value: string): SharedWorkspaceLink | null;
+/** Builds a share URL containing only nonsecret destination identifiers. */
+declare function sharedWorkspaceURL(link: SharedWorkspaceLink): string;
+//#endregion
+export { SharedWorkspaceLink, WORKSPACE_LINK_ORIGIN, parseWorkspaceLink, sharedWorkspaceURL, validHomeId };

package/dist/workspace-link.mjs

@@ -0,0 +1,50 @@
+//#region workspace-link.ts
+const WORKSPACE_LINK_ORIGIN = "https://stim.appandflow.com";
+function validHomeId(value) {
+	return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+/** Parses a v1 HTTPS workspace link; unsupported origins, destinations and ambiguous query fields return null. */
+function parseWorkspaceLink(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return null;
+	}
+	if (url.origin !== "https://stim.appandflow.com" || url.username || url.password || !["/open", "/open/"].includes(url.pathname)) return null;
+	const params = url.searchParams;
+	for (const name of [
+		"v",
+		"machine",
+		"workspace",
+		"platform",
+		"slot"
+	]) if (params.getAll(name).length > 1) return null;
+	const machine = params.get("machine");
+	const workspace = params.get("workspace");
+	if (params.get("v") !== "1" || !validHomeId(machine) || !workspace || !/^[0-9a-f]{16}$/.test(workspace)) return null;
+	const platform = params.get("platform");
+	const slot = params.get("slot");
+	const link = {
+		machine: machine.toLowerCase(),
+		workspace,
+		...slot && slot !== "default" ? { slot } : {}
+	};
+	if (platform) {
+		if (platform !== "ios" && platform !== "android" && platform !== "macos" && platform !== "web") return null;
+		link.platform = platform;
+	}
+	return link;
+}
+/** Builds a share URL containing only nonsecret destination identifiers. */
+function sharedWorkspaceURL(link) {
+	const url = new URL("/open", WORKSPACE_LINK_ORIGIN);
+	url.searchParams.set("v", "1");
+	url.searchParams.set("machine", link.machine);
+	url.searchParams.set("workspace", link.workspace);
+	if (link.platform) url.searchParams.set("platform", link.platform);
+	if (link.slot && link.slot !== "default") url.searchParams.set("slot", link.slot);
+	return url.href;
+}
+//#endregion
+export { WORKSPACE_LINK_ORIGIN, parseWorkspaceLink, sharedWorkspaceURL, validHomeId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/core",
-  "version": "1.20.1",
+  "version": "1.21.0",
   "description": "Shared internal cache and runtime primitives for Stim packages.",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,16 @@
       "module-sync": "./dist/index.mjs",
       "default": "./dist/index.mjs"
     },
+    "./noise": {
+      "types": "./dist/noise.d.mts",
+      "module-sync": "./dist/noise.mjs",
+      "default": "./dist/noise.mjs"
+    },
+    "./noise-session": {
+      "types": "./dist/noise-session.d.mts",
+      "module-sync": "./dist/noise-session.mjs",
+      "default": "./dist/noise-session.mjs"
+    },
     "./ownership-claim": {
       "types": "./dist/ownership-claim.d.mts",
       "module-sync": "./dist/ownership-claim.mjs",
@@ -56,6 +66,16 @@
       "types": "./dist/receive-protocol.d.mts",
       "module-sync": "./dist/receive-protocol.mjs",
       "default": "./dist/receive-protocol.mjs"
+    },
+    "./toolchain": {
+      "types": "./dist/toolchain.d.mts",
+      "module-sync": "./dist/toolchain.mjs",
+      "default": "./dist/toolchain.mjs"
+    },
+    "./workspace-link": {
+      "types": "./dist/workspace-link.d.mts",
+      "module-sync": "./dist/workspace-link.mjs",
+      "default": "./dist/workspace-link.mjs"
     }
   },
   "dependencies": {