@workerstack/system 0.0.0-stage → 0.3.0

package/src/path.ts

@@ -0,0 +1,172 @@
+/**
+ * Interactive-TTY PATH snapshot for `check`.
+ *
+ * `install` keeps using this process PATH. `check --here` does too.
+ */
+
+import { execFileSync } from "node:child_process"
+import { basename } from "node:path"
+
+export type PathSource = "tty" | "process"
+
+export interface PathSnapshot {
+	path: string
+	/** why the interactive shell could not be read, when `source` is `process` */
+	reason?: string
+	source: PathSource
+}
+
+export type ExecFile = (file: string, args: readonly string[], env: NodeJS.ProcessEnv) => string
+
+export const TTY_PATH_FALLBACK_WARN = "could not read interactive-shell PATH; using this process PATH"
+
+export const PATH_PRINTF = 'printf %s "$PATH"'
+export const UNIX_BASH_PATH_ARGS = ["-ic", PATH_PRINTF] as const
+export const UNIX_ZSH_PATH_ARGS = ["-lic", PATH_PRINTF] as const
+/**
+ * What a new Windows terminal does: PATH from the registry (Machine, then User, where installers and
+ * choco write), then each profile in PowerShell's startup order, then print PATH. Profiles are dot-sourced
+ * explicitly (-NoProfile) because they must run after PATH is rebuilt.
+ */
+const WINDOWS_TTY_PATH_SCRIPT = [
+	"$env:Path = [Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' + [Environment]::GetEnvironmentVariable('Path', 'User')",
+	"foreach ($p in @($PROFILE.AllUsersAllHosts, $PROFILE.AllUsersCurrentHost, $PROFILE.CurrentUserAllHosts, $PROFILE.CurrentUserCurrentHost)) { if (Test-Path $p) { . $p } }",
+	"$env:Path",
+].join("; ")
+
+export const WINDOWS_TTY_PATH_ARGS = [
+	"-NoLogo",
+	"-NoProfile",
+	"-NonInteractive",
+	"-Command",
+	WINDOWS_TTY_PATH_SCRIPT,
+] as const
+
+const defaultExecFile: ExecFile = (file, args, env) =>
+	execFileSync(file, [...args], {
+		encoding: "utf-8",
+		env,
+		stdio: ["ignore", "pipe", "pipe"],
+		timeout: 30_000,
+	})
+
+export function processPath(env: NodeJS.ProcessEnv = process.env): string {
+	return env.PATH ?? env.Path ?? ""
+}
+
+export function pathEnv(searchPath: string, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+	return { ...base, PATH: searchPath, Path: searchPath }
+}
+
+/**
+ * HOME/USER/SHELL, locale, TERM, and the Windows profile and user-dir roots a profile expands
+ * (`$env:LOCALAPPDATA\bin`). Not PATH. Not leftover toolchain exports. Not PSModulePath.
+ */
+export const TTY_ENV_KEEP = [
+	"APPDATA",
+	"ComSpec",
+	"COMSPEC",
+	"HOME",
+	"HOMEDRIVE",
+	"HOMEPATH",
+	"HOMESHARE",
+	"LANG",
+	"LANGUAGE",
+	"LOCALAPPDATA",
+	"LOGNAME",
+	"PATHEXT",
+	"ProgramData",
+	"PROGRAMDATA",
+	"ProgramFiles",
+	"PROGRAMFILES",
+	"ProgramFiles(x86)",
+	"SHELL",
+	"SYSTEMROOT",
+	"SystemRoot",
+	"TEMP",
+	"TERM",
+	"TMP",
+	"USER",
+	"USERPROFILE",
+	"WINDIR",
+	"windir",
+] as const
+
+export function isTtyEnvKeep(key: string): boolean {
+	if (key.startsWith("LC_")) return true
+	return (TTY_ENV_KEEP as readonly string[]).includes(key)
+}
+
+export function unixStockPath(): string {
+	return "/usr/local/bin:/usr/bin:/bin"
+}
+
+export function windowsStockPath(env: NodeJS.ProcessEnv): string {
+	const root = env.SYSTEMROOT || env.SystemRoot || "C:\\Windows"
+	/* Windows PowerShell lives outside System32 proper, and the snapshot spawns it by name from this PATH */
+	return `${root}\\System32;${root};${root}\\System32\\WindowsPowerShell\\v1.0`
+}
+
+/** Env for the TTY PATH spawn. Interactive rc applies the default toolchain on a stock PATH. */
+/**
+ * Unix: the keep-list, so leftover toolchain exports cannot pin a stale binary. Windows: everything but
+ * PATH and PSModulePath, because the snapshot rebuilds PATH from the registry anyway and Windows
+ * PowerShell needs its system variables to start promptly.
+ */
+export function ttySnapshotEnv(env: NodeJS.ProcessEnv, platform: NodeJS.Platform): NodeJS.ProcessEnv {
+	const out: NodeJS.ProcessEnv = {}
+	for (const [key, value] of Object.entries(env)) {
+		if (value === undefined) continue
+		const keep = platform === "win32" ? !/^(path|psmodulepath)$/i.test(key) : isTtyEnvKeep(key)
+		if (keep) out[key] = value
+	}
+	const stock = platform === "win32" ? windowsStockPath(env) : unixStockPath()
+	out.PATH = stock
+	out.Path = stock
+	return out
+}
+
+/** bash: interactive (`-ic`). zsh: login+interactive (`-lic`). Other Unix shells: `-ic`. */
+export function unixPathSnapshotArgs(shell: string): readonly [string, string] {
+	const name = basename(shell).replace(/\.exe$/i, "")
+	if (name === "zsh") return ["-lic", PATH_PRINTF]
+	return ["-ic", PATH_PRINTF]
+}
+
+/** Interactive rc may print MOTD on stdout; the PATH line is last. */
+export function parsePathOutput(out: string): string {
+	const lines = out.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n")
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const line = lines[i]?.trim()
+		if (line) return line
+	}
+	return ""
+}
+
+/**
+ * Snapshot PATH from a new interactive TTY once.
+ * Unix bash: `$SHELL -ic` with stdin `/dev/null` (not login-only `-lc`).
+ * Unix zsh: `$SHELL -lic` (`.zprofile` + `.zshrc`).
+ * Windows: `powershell.exe` rebuilding PATH from the registry, then its profiles (WINDOWS_TTY_PATH_ARGS).
+ * Spawn env is a keep-list (HOME/SHELL/locale/TERM) plus a stock PATH so leftover
+ * parent PATH and toolchain exports cannot pin a stale binary.
+ * Spawn failure or empty PATH → this process PATH (`source: "process"`).
+ */
+export function snapshotTtyPath(
+	platform: NodeJS.Platform = process.platform,
+	env: NodeJS.ProcessEnv = process.env,
+	execFile: ExecFile = defaultExecFile,
+): PathSnapshot {
+	try {
+		const childEnv = ttySnapshotEnv(env, platform)
+		const raw =
+			platform === "win32"
+				? execFile("powershell.exe", WINDOWS_TTY_PATH_ARGS, childEnv)
+				: execFile(env.SHELL || "/bin/sh", unixPathSnapshotArgs(env.SHELL || "/bin/sh"), childEnv)
+		const path = parsePathOutput(raw)
+		if (path) return { path, source: "tty" }
+		return { path: processPath(env), reason: "the shell printed no PATH", source: "process" }
+	} catch (error) {
+		return { path: processPath(env), reason: error instanceof Error ? error.message : String(error), source: "process" }
+	}
+}

package/src/platform.ts

@@ -0,0 +1,73 @@
+/**
+ * OS detection for system dependency installation
+ */
+
+import { execSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { OS_TARGETS, type OsTarget } from "./config.ts"
+import { pathEnv } from "./path.ts"
+
+/** Run a shell command and return stdout; throws on a non-zero exit. Injected so lookups are testable. */
+export type ShellExec = (command: string, env: NodeJS.ProcessEnv | undefined) => string
+
+const shellExec: ShellExec = (command, env) =>
+	execSync(command, { encoding: "utf-8", env, stdio: ["ignore", "pipe", "ignore"] })
+
+/** Resolved path of the first token (`command -v`, or `where` on Windows). Null if missing. */
+export function whichBinary(
+	command: string,
+	platform: NodeJS.Platform = process.platform,
+	searchPath?: string,
+	exec: ShellExec = shellExec,
+): string | null {
+	const token = command.replace(/^["']|["']$/g, "")
+	if (!token) return null
+	if (existsSync(token)) return token
+	const lookup = platform === "win32" ? `where ${token}` : `command -v ${token}`
+	try {
+		const out = exec(lookup, searchPath === undefined ? undefined : pathEnv(searchPath))
+		/* `where` lists every match, one per line; the first is what the shell runs */
+		return out.trim().split(/\r?\n/)[0] || null
+	} catch {
+		return null
+	}
+}
+
+export function commandExists(command: string, searchPath?: string): boolean {
+	return whichBinary(command, process.platform, searchPath) !== null
+}
+
+export function parseOsTarget(value: string): OsTarget {
+	if ((OS_TARGETS as readonly string[]).includes(value)) return value as OsTarget
+	throw new Error(`Unknown OS target: ${value}. Expected one of: ${OS_TARGETS.join(", ")}`)
+}
+
+/** True when `command` resolves on PATH. Injected so detection is testable without the host's tools. */
+export type CommandProbe = (command: string) => boolean
+
+export function detectLinuxDistro(has: CommandProbe = commandExists): OsTarget {
+	if (has("apt-get")) return "linux-apt"
+	if (has("dnf")) return "linux-dnf"
+	if (has("pacman")) return "linux-pacman"
+	/* default to apt if nothing detected */
+	return "linux-apt"
+}
+
+export function detectOsFromPlatform(
+	platform: NodeJS.Platform,
+	override: string | undefined = process.env.WORKERSTACK_SYSTEM_OS,
+	has: CommandProbe = commandExists,
+): OsTarget {
+	if (override) return parseOsTarget(override)
+	if (platform === "darwin") return "macos"
+	if (platform === "win32") return "windows"
+	return detectLinuxDistro(has)
+}
+
+/**
+ * Detect the current OS target.
+ * `override` (or `WORKERSTACK_SYSTEM_OS`) forces a target — used by tests and `--os`.
+ */
+export function detectOs(override: string | undefined = process.env.WORKERSTACK_SYSTEM_OS): OsTarget {
+	return detectOsFromPlatform(process.platform, override)
+}

package/src/probe.ts

@@ -0,0 +1,44 @@
+/**
+ * What is installed: the check command's binary, where it resolves, and the version it reports.
+ */
+
+import { type OsTarget, resolveCheckCommand, type SystemDepConfig } from "./config.ts"
+import type { Runtime } from "./runtime.ts"
+import { parseVersion } from "./version.ts"
+
+/** Everything a command needs: the effects, the resolved deps, and where the config lives. */
+export interface Context {
+	configDir: string
+	deps: Record<string, SystemDepConfig>
+	os: OsTarget
+	packageJsonPath: string
+	rt: Runtime
+}
+
+/** First token of the check command: the binary whose presence and path are probed. */
+export function checkBinary(name: string, config: SystemDepConfig): string {
+	return resolveCheckCommand(name, config).split(/\s+/)[0] as string
+}
+
+export interface Installed {
+	/** where the check binary resolves */
+	path: string
+	/** parsed from the check output (`check.pattern`, else the first `N.N…`) */
+	version: string
+}
+
+/** The installed binary and the version it reports, or null when it is missing or reports none. */
+export function probeInstalled(
+	rt: Runtime,
+	name: string,
+	config: SystemDepConfig,
+	searchPath?: string,
+): Installed | null {
+	const path = rt.which(checkBinary(name, config), searchPath)
+	if (path === null) return null
+	const command = resolveCheckCommand(name, config)
+	const result = rt.capture(command, searchPath)
+	if (result.timedOut) rt.warn(`   ${name}: check timed out: ${command}`)
+	const version = result.ok ? parseVersion(result.stdout, config.check?.pattern) : null
+	return version === null ? null : { path, version }
+}

package/src/runtime.ts

@@ -0,0 +1,99 @@
+/**
+ * Every side effect the CLI performs, behind one interface. Commands take a `Runtime` and return an exit
+ * code, so tests drive them with a fake and only `bin.ts` touches `process`.
+ */
+
+import { execSync } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { delimiter, dirname } from "node:path"
+import { pathToFileURL } from "node:url"
+import { runShellCommand } from "./exec.ts"
+import { type PathSnapshot, pathEnv, snapshotTtyPath } from "./path.ts"
+import { whichBinary } from "./platform.ts"
+
+export interface CaptureResult {
+	ok: boolean
+	stdout: string
+	/** the command was killed after the check timeout */
+	timedOut: boolean
+}
+
+export interface RuntimeOptions {
+	/** Kill a check command after this long. Default 30s, so a hanging `--version` cannot hang a run. */
+	checkTimeoutMs?: number
+	/** The environment commands run in and PATH changes go to. Default `process.env`. */
+	env?: NodeJS.ProcessEnv
+}
+
+export interface Runtime {
+	readonly arch: string
+	readonly cwd: string
+	readonly env: NodeJS.ProcessEnv
+	readonly home: string
+	readonly platform: NodeJS.Platform
+	/** Run a check command and capture stdout. `searchPath` replaces PATH for the child. */
+	capture(command: string, searchPath?: string): CaptureResult
+	error(line: string): void
+	exists(path: string): boolean
+	importModule(path: string): Promise<Record<string, unknown>>
+	log(line: string): void
+	/** Put `dir` first on this process's PATH (once), so later commands in the run find what it holds. */
+	prependPath(dir: string): void
+	readFile(path: string): string
+	/** Run an install command with inherited stdio. True on exit 0. */
+	run(command: string): boolean
+	ttyPath(): PathSnapshot
+	warn(line: string): void
+	/** Resolved path of the first token, or null. `searchPath` replaces PATH for the lookup. */
+	which(token: string, searchPath?: string): string | null
+	/** Write a file, creating parent directories. */
+	writeFile(path: string, content: string): void
+}
+
+export function nodeRuntime({ checkTimeoutMs = 30_000, env = process.env }: RuntimeOptions = {}): Runtime {
+	return {
+		arch: process.arch,
+		capture(command, searchPath) {
+			try {
+				const stdout = execSync(command, {
+					encoding: "utf-8",
+					env: searchPath === undefined ? env : pathEnv(searchPath, env),
+					stdio: ["pipe", "pipe", "pipe"],
+					timeout: checkTimeoutMs,
+				})
+				return { ok: true, stdout: stdout.trim(), timedOut: false }
+			} catch (error) {
+				return { ok: false, stdout: "", timedOut: (error as { code?: string }).code === "ETIMEDOUT" }
+			}
+		},
+		cwd: process.cwd(),
+		env,
+		error: (line) => console.error(line),
+		exists: (path) => existsSync(path),
+		home: homedir(),
+		importModule: async (path) => (await import(pathToFileURL(path).href)) as Record<string, unknown>,
+		log: (line) => console.log(line),
+		platform: process.platform,
+		prependPath(dir) {
+			const parts = (env.PATH ?? "").split(delimiter).filter(Boolean)
+			if (!parts.includes(dir)) env.PATH = [dir, ...parts].join(delimiter)
+		},
+		readFile: (path) => readFileSync(path, "utf-8"),
+		run(command) {
+			try {
+				runShellCommand(command, process.platform, env)
+				return true
+			} catch {
+				return false
+			}
+		},
+		ttyPath: () => snapshotTtyPath(),
+		warn: (line) => console.warn(line),
+		which: (token, searchPath) => whichBinary(token, process.platform, searchPath),
+		writeFile(path, content) {
+			mkdirSync(dirname(path), { recursive: true })
+			writeFileSync(path, content)
+		},
+	}
+}

package/src/validate.ts

@@ -0,0 +1,154 @@
+/**
+ * Shape check for a loaded config. Collects every problem with its path, then throws one `ConfigError`,
+ * so a typo fails before anything installs instead of mid-run.
+ */
+
+import { OS_TARGETS, type SystemConfig } from "./config.ts"
+import { ConfigError } from "./errors.ts"
+
+type Record_ = Record<string, unknown>
+
+const TOP_KEYS = ["deps", "packageJsonPath"]
+const DEP_KEYS = ["check", "dependsOn", "description", "env", "os", "required", "version"]
+const CHECK_KEYS = ["command", "pattern"]
+const OS_KEYS = ["all", ...OS_TARGETS]
+const ENV_SHAPE = "must be { path }, { key, value } or { key, detect, fallback? }"
+
+function isObject(value: unknown): value is Record_ {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function isText(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0
+}
+
+function isTextList(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string")
+}
+
+function compiles(source: string): boolean {
+	try {
+		return new RegExp(source) instanceof RegExp
+	} catch {
+		return false
+	}
+}
+
+function unknownKeys(value: Record_, allowed: readonly string[], at: string, problems: string[]): void {
+	for (const key of Object.keys(value)) {
+		if (!allowed.includes(key)) problems.push(`${at}${key}: unknown key (allowed: ${allowed.join(", ")})`)
+	}
+}
+
+function checkOs(os: unknown, at: string, problems: string[], allowEmpty: boolean): void {
+	if (!isObject(os)) {
+		problems.push(`${at}: must be an object of commands`)
+		return
+	}
+	if (!allowEmpty && Object.keys(os).length === 0) problems.push(`${at}: must name at least one OS key or all`)
+	for (const [key, command] of Object.entries(os)) {
+		if (key === "all") {
+			if (!isText(command)) problems.push(`${at}.all: must be a command string`)
+		} else if (!OS_KEYS.includes(key)) {
+			problems.push(`${at}.${key}: unknown OS (allowed: ${OS_KEYS.join(", ")})`)
+		} else if (command !== false && !isText(command)) {
+			problems.push(`${at}.${key}: must be a command string or false`)
+		}
+	}
+}
+
+function checkCheck(check: unknown, at: string, problems: string[]): void {
+	if (!isObject(check)) {
+		problems.push(`${at}: must be an object like { command }`)
+		return
+	}
+	if (!isText(check.command)) problems.push(`${at}.command: must be a non-empty string`)
+	if (check.pattern !== undefined) {
+		if (typeof check.pattern !== "string") problems.push(`${at}.pattern: must be a regex source string`)
+		else if (!compiles(check.pattern)) problems.push(`${at}.pattern: invalid regex`)
+	}
+	unknownKeys(check, CHECK_KEYS, `${at}.`, problems)
+}
+
+function checkEnvEntry(entry: unknown, at: string, problems: string[]): void {
+	if (!isObject(entry)) {
+		problems.push(`${at}: ${ENV_SHAPE}`)
+		return
+	}
+	if ("appendToPath" in entry) {
+		problems.push(`${at}: appendToPath is gone; use { path: ${JSON.stringify(entry.value)} } (it goes first on PATH)`)
+		return
+	}
+	if ("path" in entry) {
+		if (!isText(entry.path)) problems.push(`${at}.path: must be a non-empty string`)
+		return
+	}
+	if (!("value" in entry) && !("detect" in entry)) {
+		problems.push(`${at}: ${ENV_SHAPE}`)
+		return
+	}
+	if (!isText(entry.key)) problems.push(`${at}.key: must be a non-empty string`)
+	if ("value" in entry) {
+		if (typeof entry.value !== "string") problems.push(`${at}.value: must be a string`)
+		return
+	}
+	if (!isTextList(entry.detect)) problems.push(`${at}.detect: must be a list of paths`)
+	if (entry.fallback !== undefined && typeof entry.fallback !== "string") {
+		problems.push(`${at}.fallback: must be a string`)
+	}
+}
+
+/**
+ * Problems with one dep entry, each prefixed with `at` (e.g. `deps.go`). A custom dep needs description,
+ * version, required and a non-empty os. A built-in takes a version string, or an object whose only
+ * required field is version; its os merges over the catalog's, so it may be empty.
+ */
+export function checkDep(dep: unknown, at: string, problems: string[], builtin: boolean): void {
+	if (builtin && (typeof dep === "string" || !isObject(dep))) {
+		if (!isText(dep)) problems.push(`${at}: must be a version string or { version, ... }`)
+		return
+	}
+	if (!isObject(dep)) {
+		problems.push(`${at}: must be an object`)
+		return
+	}
+	if (!builtin || dep.description !== undefined) {
+		if (!isText(dep.description)) problems.push(`${at}.description: must be a non-empty string`)
+	}
+	if (!isText(dep.version)) problems.push(`${at}.version: must be a non-empty string`)
+	if (!builtin || dep.required !== undefined) {
+		if (typeof dep.required !== "boolean") problems.push(`${at}.required: must be true or false`)
+	}
+	if (!builtin || dep.os !== undefined) checkOs(dep.os, `${at}.os`, problems, builtin)
+	if (dep.check !== undefined) checkCheck(dep.check, `${at}.check`, problems)
+	if (dep.dependsOn !== undefined && !isTextList(dep.dependsOn)) {
+		problems.push(`${at}.dependsOn: must be a list of dep names`)
+	}
+	if (dep.env !== undefined) {
+		if (!Array.isArray(dep.env)) problems.push(`${at}.env: must be a list`)
+		else dep.env.forEach((entry, i) => checkEnvEntry(entry, `${at}.env[${i}]`, problems))
+	}
+	unknownKeys(dep, DEP_KEYS, `${at}.`, problems)
+}
+
+/**
+ * `config` typed as a `SystemConfig`, or a `ConfigError` listing every problem.
+ * Names in `builtins` take the built-in entry forms.
+ */
+export function validateConfig(config: unknown, builtins: ReadonlySet<string> = new Set()): SystemConfig {
+	const problems: string[] = []
+	if (!isObject(config)) {
+		problems.push("config: must be an object like { deps: { ... } }")
+	} else {
+		if (!isObject(config.deps)) problems.push("deps: must be an object of dependencies")
+		else
+			for (const [name, dep] of Object.entries(config.deps)) checkDep(dep, `deps.${name}`, problems, builtins.has(name))
+		if (config.packageJsonPath !== undefined && typeof config.packageJsonPath !== "string") {
+			problems.push("packageJsonPath: must be a string")
+		}
+		unknownKeys(config, TOP_KEYS, "", problems)
+	}
+	if (problems.length > 0)
+		throw new ConfigError(`Invalid system config:\n${problems.map((p) => `  - ${p}`).join("\n")}`)
+	return config as SystemConfig
+}

package/src/version.ts

@@ -0,0 +1,33 @@
+/**
+ * Version parsing and matching for `check` and `install`.
+ */
+
+const DEFAULT_PATTERN = /(\d+\.\d+[\w.-]*)/
+
+/** The first capture of `pattern` (a regex source), else the first dotted version, else null. */
+export function parseVersion(output: string, pattern?: string): string | null {
+	const match = output.match(pattern === undefined ? DEFAULT_PATTERN : new RegExp(pattern))
+	return match?.[1] ?? null
+}
+
+function strip(version: string): string {
+	return version.replace(/^v/, "")
+}
+
+/**
+ * Whether `installed` satisfies the pinned `expected`.
+ * - `latest` matches anything.
+ * - Plain versions match when expected's dot segments prefix installed's: `22` matches `22.20.0`,
+ *   `1.27.1` matches `1.27.1` and `1.27.1.4`, but never `1.27.10`.
+ * - Build metadata (`+9`, and anything after it) on the installed side is ignored unless the pin has some,
+ *   as in semver: `21` matches Temurin's `21.0.13+9`. A pin with `+` matches exactly.
+ * - A prerelease (`-beta.12`) on either side must match exactly.
+ */
+export function versionsMatch(installed: string, expected: string): boolean {
+	if (expected === "latest") return true
+	const want = strip(expected)
+	const have = want.includes("+") ? strip(installed) : (strip(installed).split("+")[0] as string)
+	if (/[-+]/.test(have) || /[-+]/.test(want)) return have === want
+	const haveParts = have.split(".")
+	return want.split(".").every((part, i) => haveParts[i] === part)
+}