@workerstack/system 0.0.0-stage → 0.2.3

package/src/config.ts

@@ -0,0 +1,120 @@
+/**
+ * System dependencies configuration helpers
+ *
+ * Template variables available in `os` commands and `check.command`:
+ *   {{name}}    — dep key (e.g. "node", "stripe-cli")
+ *   {{version}} — full version string (e.g. "22.20.0")
+ *   {{major}}   — major version number (e.g. "22")
+ *   {{arch}}    — CPU architecture: "arm64" or "amd64" (auto-detected)
+ */
+
+export const OS_TARGETS = ["linux-apt", "linux-dnf", "linux-pacman", "macos", "windows"] as const
+
+export type OsTarget = (typeof OS_TARGETS)[number]
+
+/**
+ * Per-OS install commands.
+ * - Use specific OS keys for platform-specific commands
+ * - Use "all" for commands identical across all platforms
+ * - Per-OS keys override "all" when both are present
+ * - Omit an OS key (without "all") = unavailable on that OS
+ * - Set an OS key to `false` = explicitly unavailable on that OS (overrides "all")
+ */
+export type OsCommands = Partial<Record<OsTarget, string | false>> & { all?: string }
+
+export interface EnvVar {
+	/** Environment variable name */
+	key: string
+	/** Value (supports $HOME and other env refs). Can be omitted if detect is provided. */
+	value?: string
+	/** If true, appends to PATH instead of setting directly */
+	appendToPath?: boolean
+	/** Auto-detect value from these paths (first existing path wins). Supports $HOME. */
+	detect?: string[]
+	/** Fallback value if detect finds nothing */
+	fallback?: string
+}
+
+export interface SystemDepConfig {
+	description: string
+	required: boolean
+	version: string
+	/** Per-OS install commands. Supports {{name}}, {{version}}, {{major}} templates. */
+	os: OsCommands
+	/**
+	 * Version check command. Supports {{name}} template.
+	 * Default: "{{name}} --version" — only declare when it differs.
+	 */
+	check?: { command: string }
+	/** Deps that must be installed before this one (by dep key name) */
+	dependsOn?: string[]
+	/** Env vars to configure after install */
+	env?: EnvVar[]
+}
+
+export interface SystemConfig {
+	/** Path to package.json for packageManager sync. Relative to config file directory. */
+	packageJsonPath?: string
+	deps: Record<string, SystemDepConfig>
+}
+
+/**
+ * Interpolate {{name}}, {{version}}, {{major}} in a string
+ */
+function detectArch(): string {
+	if (process.arch === "arm64") return "arm64"
+	return "amd64"
+}
+
+/** Same table `check` uses. `"latest"` matches anything with a parsed version. */
+export function versionsMatch(installed: string, expected: string): boolean {
+	return expected === "latest" || installed === expected || expected.includes(installed) || installed.includes(expected)
+}
+
+export function interpolate(template: string, name: string, version: string): string {
+	const major = version.split(".")[0] ?? version
+	return template
+		.replace(/\{\{name\}\}/g, name)
+		.replace(/\{\{version\}\}/g, version)
+		.replace(/\{\{major\}\}/g, major)
+		.replace(/\{\{arch\}\}/g, detectArch())
+}
+
+/**
+ * Resolve the install command for a dep on a given OS target.
+ * Returns the interpolated command, or null if unavailable.
+ */
+export function resolveOsCommand(name: string, config: SystemDepConfig, target: OsTarget): string | null {
+	const specific = config.os[target]
+
+	/* explicitly unavailable */
+	if (specific === false) return null
+
+	/* prefer specific OS command, fall back to "all" */
+	const raw = specific ?? config.os.all
+	if (!raw) return null
+
+	return interpolate(raw, name, config.version)
+}
+
+/**
+ * Resolve the version check command for a dep.
+ * Default: "{name} --version"
+ */
+export function resolveCheckCommand(name: string, config: SystemDepConfig): string {
+	const raw = config.check?.command ?? "{{name}} --version"
+	return interpolate(raw, name, config.version)
+}
+
+/**
+ * Helper to define system dependencies configuration with type safety
+ */
+export function defineConfig(options: {
+	packageJsonPath?: string
+	deps: Record<string, SystemDepConfig>
+}): SystemConfig {
+	return {
+		deps: options.deps,
+		packageJsonPath: options.packageJsonPath ?? "package.json",
+	}
+}

package/src/env.ts

@@ -0,0 +1,85 @@
+import { mkdirSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+
+export type ShellKind = "posix" | "powershell"
+
+export function shellKind(platform: NodeJS.Platform): ShellKind {
+	return platform === "win32" ? "powershell" : "posix"
+}
+
+export function shellConfigPath(home: string, kind: ShellKind, shell = ""): string {
+	if (kind === "powershell") {
+		return resolve(home, "Documents", "PowerShell", "Microsoft.PowerShell_profile.ps1")
+	}
+	if (shell.includes("zsh")) return resolve(home, ".zshrc")
+	return resolve(home, ".bashrc")
+}
+
+export function expandPath(path: string, home: string, env: NodeJS.ProcessEnv = process.env): string {
+	return path
+		.replace(/\$HOME/g, home)
+		.replace(/%USERPROFILE%/gi, home)
+		.replace(/%HOME%/gi, home)
+		.replace(/\$ANDROID_HOME/g, env.ANDROID_HOME || "")
+		.replace(/%ANDROID_HOME%/gi, env.ANDROID_HOME || "")
+}
+
+export const MARKER_OWNER = "@workerstack/system"
+
+/** Owner tag written before the rename; blocks carrying it are replaced, never duplicated. */
+export const LEGACY_MARKER_OWNER = "crossdeps"
+
+export function envMarkers(tool: string, owner: string = MARKER_OWNER): { end: string; start: string } {
+	return {
+		end: `# end ${tool} environment`,
+		start: `# ${tool} environment (managed by ${owner})`,
+	}
+}
+
+function escapeRegExp(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+function stripBlock(existing: string, tool: string, owner: string): string {
+	const { end, start } = envMarkers(tool, owner)
+	if (!existing.includes(start)) return existing
+	return existing.replace(new RegExp(`\\r?\\n?${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}\\r?\\n?`, "g"), "")
+}
+
+export function renderEnvBlock(
+	tool: string,
+	envs: Array<{ appendToPath?: boolean; key: string; value: string }>,
+	kind: ShellKind,
+): string {
+	const { end, start } = envMarkers(tool)
+	const nl = kind === "powershell" ? "\r\n" : "\n"
+	const lines = ["", start]
+	for (const env of envs) {
+		if (env.appendToPath) {
+			lines.push(kind === "powershell" ? `$env:Path += ";${env.value}"` : `export PATH="$PATH:${env.value}"`)
+		} else {
+			lines.push(kind === "powershell" ? `$env:${env.key} = "${env.value}"` : `export ${env.key}="${env.value}"`)
+		}
+	}
+	lines.push(end, "")
+	return lines.join(nl)
+}
+
+export function applyEnvBlock(existing: string, block: string, tool: string): string {
+	const withoutLegacy = stripBlock(existing, tool, LEGACY_MARKER_OWNER)
+	return stripBlock(withoutLegacy, tool, MARKER_OWNER) + block
+}
+
+/** True when the rc already holds a block for `tool`, current or legacy. */
+export function hasEnvBlock(existing: string, tool: string): boolean {
+	return existing.includes(envMarkers(tool).start) || existing.includes(envMarkers(tool, LEGACY_MARKER_OWNER).start)
+}
+
+export function ensureParentDir(filePath: string): void {
+	mkdirSync(dirname(filePath), { recursive: true })
+}
+
+export function reloadHint(kind: ShellKind, configName: string): string {
+	if (kind === "powershell") return "Restart PowerShell or run: . $PROFILE"
+	return `Run: source ~/${configName}   (or restart terminal)`
+}

package/src/exec.ts

@@ -0,0 +1,43 @@
+import { execFileSync, execSync } from "node:child_process"
+
+export type ShellInvocation = { args: string[]; file: string } | { command: string; shell: string }
+
+const POWERSHELL_MARKERS = [
+	/\birm\b/i,
+	/\biex\b/i,
+	/\$env:/,
+	/Invoke-WebRequest/i,
+	/Invoke-Expression/i,
+	/New-Item\b/i,
+	/Test-Path\b/i,
+	/Out-Null/i,
+	/Get-Command\b/i,
+	/\$LASTEXITCODE/,
+]
+
+export function needsPowerShell(command: string): boolean {
+	return POWERSHELL_MARKERS.some((re) => re.test(command))
+}
+
+export function shellInvocation(command: string, platform: NodeJS.Platform = process.platform): ShellInvocation {
+	if (platform === "win32") {
+		if (needsPowerShell(command)) {
+			return {
+				args: ["-NoProfile", "-NonInteractive", "-Command", command],
+				file: "powershell.exe",
+			}
+		}
+		/* cmd.exe so bun -e / choco / || keep working */
+		return { command, shell: process.env.ComSpec || "cmd.exe" }
+	}
+	return { command, shell: "/bin/bash" }
+}
+
+export function runShellCommand(command: string, platform: NodeJS.Platform = process.platform): void {
+	const invocation = shellInvocation(command, platform)
+	if ("file" in invocation) {
+		execFileSync(invocation.file, invocation.args, { stdio: "inherit" })
+		return
+	}
+	execSync(invocation.command, { shell: invocation.shell, stdio: "inherit" })
+}

package/src/graph.ts

@@ -0,0 +1,45 @@
+import type { SystemDepConfig } from "./config.ts"
+
+/**
+ * Topological sort of deps respecting `dependsOn` field.
+ * Returns dep names in install order.
+ */
+export function sortByDependencies(depEntries: Array<[string, SystemDepConfig]>): Array<[string, SystemDepConfig]> {
+	const nameSet = new Set(depEntries.map(([name]) => name))
+	const sorted: Array<[string, SystemDepConfig]> = []
+	const visited = new Set<string>()
+	const visiting = new Set<string>()
+
+	const depMap = new Map(depEntries)
+
+	function visit(name: string): void {
+		if (visited.has(name)) return
+		if (visiting.has(name)) {
+			console.warn(`Circular dependency detected involving: ${name}`)
+			return
+		}
+
+		visiting.add(name)
+
+		const config = depMap.get(name)
+		if (config?.dependsOn) {
+			for (const dep of config.dependsOn) {
+				if (nameSet.has(dep)) {
+					visit(dep)
+				}
+			}
+		}
+
+		visiting.delete(name)
+		visited.add(name)
+		if (config) {
+			sorted.push([name, config])
+		}
+	}
+
+	for (const [name] of depEntries) {
+		visit(name)
+	}
+
+	return sorted
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @workerstack/system — cross-platform system dependency manager
+ */
+
+export type { SystemConfig, EnvVar, OsCommands, OsTarget, SystemDepConfig } from "./config.ts"
+export {
+	defineConfig,
+	interpolate,
+	OS_TARGETS,
+	resolveCheckCommand,
+	resolveOsCommand,
+	versionsMatch,
+} from "./config.ts"
+export { sortByDependencies } from "./graph.ts"
+export { commandExists, commandLookup, detectOs, detectOsFromPlatform, parseOsTarget, whichBinary } from "./platform.ts"

package/src/path.ts

@@ -0,0 +1,134 @@
+/**
+ * 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
+	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
+export const WINDOWS_TTY_PATH_ARGS = ["-NoLogo", "-NonInteractive", "-Command", "$env:Path"] 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, Windows profile roots. Not PATH. Not leftover toolchain exports. */
+export const TTY_ENV_KEEP = [
+	"ComSpec",
+	"COMSPEC",
+	"HOME",
+	"HOMEDRIVE",
+	"HOMEPATH",
+	"HOMESHARE",
+	"LANG",
+	"LANGUAGE",
+	"LOGNAME",
+	"PATHEXT",
+	"SHELL",
+	"SYSTEMROOT",
+	"SystemRoot",
+	"TERM",
+	"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"
+	return `${root}\\System32;${root}`
+}
+
+/** Env for the TTY PATH spawn. Interactive rc applies the default toolchain on a stock PATH. */
+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
+		if (isTtyEnvKeep(key)) 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` with profile (`$env:Path`), not `-NoProfile`.
+ * 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" }
+	} catch {
+		/* fall through */
+	}
+	return { path: processPath(env), source: "process" }
+}

package/src/platform.ts

@@ -0,0 +1,78 @@
+/**
+ * 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"
+
+export function commandLookup(command: string, platform: NodeJS.Platform = process.platform): string {
+	return platform === "win32" ? `where ${command} >nul 2>&1` : `command -v ${command} >/dev/null 2>&1`
+}
+
+export function commandExists(command: string, searchPath?: string): boolean {
+	const unquoted = command.replace(/^["']|["']$/g, "")
+	if (existsSync(unquoted)) return true
+	const opts = searchPath !== undefined ? { env: pathEnv(searchPath) } : undefined
+	try {
+		execSync(commandLookup(command), opts)
+		return true
+	} catch {
+		return false
+	}
+}
+
+/** Resolved path of the first token (`command -v` / `where`). Null if missing. */
+export function whichBinary(
+	command: string,
+	platform: NodeJS.Platform = process.platform,
+	searchPath?: string,
+): string | null {
+	const token = command.replace(/^["']|["']$/g, "")
+	if (!token) return null
+	if (existsSync(token)) return token
+	const opts: { encoding: "utf-8"; env?: NodeJS.ProcessEnv } = { encoding: "utf-8" }
+	if (searchPath !== undefined) opts.env = pathEnv(searchPath)
+	try {
+		if (platform === "win32") {
+			const out = execSync(`where ${token}`, opts).trim()
+			return out.split(/\r?\n/).find(Boolean) ?? null
+		}
+		const out = execSync(`command -v ${token}`, opts).trim()
+		return out || null
+	} catch {
+		return 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(", ")}`)
+}
+
+function detectLinuxDistro(): OsTarget {
+	if (commandExists("apt-get")) return "linux-apt"
+	if (commandExists("dnf")) return "linux-dnf"
+	if (commandExists("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,
+): OsTarget {
+	if (override) return parseOsTarget(override)
+	if (platform === "darwin") return "macos"
+	if (platform === "win32") return "windows"
+	return detectLinuxDistro()
+}
+
+/**
+ * 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)
+}