@workerstack/system 0.0.0-stage → 0.3.0

package/src/builtins/release.ts

@@ -0,0 +1,133 @@
+/**
+ * Release and CI tooling: git, gh, jq, curl, goreleaser, cosign, shellcheck, pwsh.
+ */
+
+import { archive, binary, localBinEnv, pick, tree, unix, winArchive, winBinary, winTree } from "./recipes.ts"
+import type { BuiltinDep } from "./types.ts"
+
+const GH = "https://github.com"
+
+export const RELEASE = {
+	curl: {
+		dependsOn: ["brew", "choco"],
+		description: "HTTP client the install commands use (the OS package manager's current build)",
+		os: () => ({
+			"linux-apt": "sudo apt-get install -y curl",
+			"linux-dnf": "sudo dnf install -y curl",
+			"linux-pacman": "sudo pacman -S --noconfirm curl",
+			macos: "brew install curl",
+			windows: "choco install curl -y",
+		}),
+		versions: "latest",
+	},
+	git: {
+		dependsOn: ["brew", "choco"],
+		description: "Version control (the OS package manager's current build)",
+		os: () => ({
+			"linux-apt": "sudo apt-get install -y git",
+			"linux-dnf": "sudo dnf install -y git",
+			"linux-pacman": "sudo pacman -S --noconfirm git",
+			macos: "brew install git",
+			windows: "choco install git -y",
+		}),
+		versions: "latest",
+	},
+	gh: {
+		description: "GitHub CLI, for releases, PRs and the API",
+		env: localBinEnv,
+		os: ({ arch, version }) => {
+			const a = pick(arch, { arm64: "arm64", x64: "amd64" })
+			const base = `${GH}/cli/cli/releases/download/v${version}/gh_${version}`
+			return {
+				...unix(
+					archive(`${base}_linux_${a}.tar.gz`, `gh_${version}_linux_${a}/bin/gh`, "gh"),
+					archive(`${base}_macOS_${a}.zip`, `gh_${version}_macOS_${a}/bin/gh`, "gh"),
+				),
+				windows: winArchive(`${base}_windows_amd64.zip`, "bin\\gh.exe", "gh"),
+			}
+		},
+		versions: "pinned",
+	},
+	goreleaser: {
+		check: { command: "goreleaser --version", pattern: "GitVersion:\\s+v?(\\d+\\.\\d+\\.\\d+)" },
+		description: "Release automation for the generated Go CLI",
+		env: localBinEnv,
+		os: ({ arch, version }) => {
+			const base = `${GH}/goreleaser/goreleaser/releases/download/v${version}/goreleaser`
+			const a = pick(arch, { arm64: "arm64", x64: "x86_64" })
+			return {
+				...unix(
+					archive(`${base}_Linux_${a}.tar.gz`, "goreleaser", "goreleaser"),
+					archive(`${base}_Darwin_${a}.tar.gz`, "goreleaser", "goreleaser"),
+				),
+				windows: winArchive(`${base}_Windows_x86_64.zip`, "goreleaser.exe", "goreleaser"),
+			}
+		},
+		versions: "pinned",
+	},
+	cosign: {
+		check: { command: "cosign version", pattern: "GitVersion:\\s+v?(\\d+\\.\\d+\\.\\d+)" },
+		description: "Sigstore signing for release artifacts",
+		env: localBinEnv,
+		os: ({ arch, version }) => {
+			const base = `${GH}/sigstore/cosign/releases/download/v${version}/cosign`
+			const a = pick(arch, { arm64: "arm64", x64: "amd64" })
+			return {
+				...unix(binary(`${base}-linux-${a}`, "cosign"), binary(`${base}-darwin-${a}`, "cosign")),
+				windows: winBinary(`${base}-windows-amd64.exe`, "cosign"),
+			}
+		},
+		versions: "pinned",
+	},
+	jq: {
+		description: "JSON processor",
+		env: localBinEnv,
+		os: ({ arch, version }) => {
+			const base = `${GH}/jqlang/jq/releases/download/jq-${version}/jq`
+			const a = pick(arch, { arm64: "arm64", x64: "amd64" })
+			return {
+				...unix(binary(`${base}-linux-${a}`, "jq"), binary(`${base}-macos-${a}`, "jq")),
+				windows: winBinary(`${base}-windows-amd64.exe`, "jq"),
+			}
+		},
+		versions: "pinned",
+	},
+	pwsh: {
+		check: { command: "pwsh --version" },
+		description: "PowerShell 7, for the generated Windows install scripts",
+		env: (os) => (os === "windows" ? [{ path: "$env:LOCALAPPDATA\\Programs\\pwsh" }] : localBinEnv(os)),
+		os: ({ arch, version }) => {
+			const base = `${GH}/PowerShell/PowerShell/releases/download/v${version}`
+			const a = pick(arch, { arm64: "arm64", x64: "x64" })
+			const dir = "$HOME/.local/share/pwsh"
+			const linux = `${tree(`${base}/powershell-${version}-linux-${a}.tar.gz`, dir, { bins: ["pwsh"] })} && chmod +x "${dir}/pwsh"`
+			return {
+				...unix(
+					linux,
+					`${tree(`${base}/powershell-${version}-osx-${a}.tar.gz`, dir, { bins: ["pwsh"] })} && chmod +x "${dir}/pwsh"`,
+				),
+				/* Fedora images lack the ICU library PowerShell needs at startup */
+				"linux-dnf": `sudo dnf install -y libicu && ${linux}`,
+				windows: winTree(`${base}/PowerShell-${version}-win-x64.zip`, "$env:LOCALAPPDATA\\Programs\\pwsh"),
+			}
+		},
+		versions: "pinned",
+	},
+	shellcheck: {
+		description: "Shell script linter, for the generated install scripts",
+		env: localBinEnv,
+		os: ({ arch, version }) => {
+			const base = `${GH}/koalaman/shellcheck/releases/download/v${version}/shellcheck-v${version}`
+			const a = pick(arch, { arm64: "aarch64", x64: "x86_64" })
+			const member = `shellcheck-v${version}/shellcheck`
+			return {
+				...unix(
+					archive(`${base}.linux.${a}.tar.xz`, member, "shellcheck"),
+					archive(`${base}.darwin.${a}.tar.xz`, member, "shellcheck"),
+				),
+				windows: winArchive(`${base}.zip`, "shellcheck.exe", "shellcheck"),
+			}
+		},
+		versions: "pinned",
+	},
+} satisfies Record<string, BuiltinDep>

package/src/builtins/resolve.ts

@@ -0,0 +1,80 @@
+import type { OsTarget, SystemDepConfig } from "../config.ts"
+import { ConfigError } from "../errors.ts"
+import type { Arch, BuiltinDep, BuiltinOverride } from "./types.ts"
+
+/** A config entry before resolution: a built-in's version or override, or a full custom dep. */
+export type RawEntry = BuiltinOverride | SystemDepConfig | string
+
+function isArch(arch: string): arch is Arch {
+	return arch === "x64" || arch === "arm64"
+}
+
+function expand(builtin: BuiltinDep, entry: BuiltinOverride | string, arch: Arch, os: OsTarget): SystemDepConfig {
+	const o: BuiltinOverride = typeof entry === "string" ? { version: entry } : entry
+	const config: SystemDepConfig = {
+		description: o.description ?? builtin.description,
+		os: { ...builtin.os({ arch, version: o.version }), ...o.os },
+		required: o.required ?? true,
+		version: o.version,
+	}
+	const check = o.check ?? builtin.check
+	const dependsOn = o.dependsOn ?? builtin.dependsOn
+	const env = o.env ?? builtin.env?.(os)
+	if (check) config.check = check
+	if (dependsOn) config.dependsOn = [...dependsOn]
+	if (env) config.env = [...env]
+	return config
+}
+
+/**
+ * Every entry as a full `SystemDepConfig`. Built-in names expand from `catalog` for `arch` and `os`; other names
+ * pass through. A `latest`-only built-in that a dep needs is added when missing. Throws `ConfigError`
+ * listing every version-policy, prerequisite and CPU problem.
+ */
+export function resolveDeps(
+	deps: Record<string, RawEntry>,
+	{ arch, os }: { arch: string; os: OsTarget },
+	catalog: Readonly<Record<string, BuiltinDep>>,
+): Record<string, SystemDepConfig> {
+	const problems: string[] = []
+	const usesBuiltin = Object.keys(deps).some((name) => name in catalog)
+	if (usesBuiltin && !isArch(arch)) {
+		throw new ConfigError(`Invalid system config:\n  - built-in deps support x64 and arm64; this machine is ${arch}`)
+	}
+
+	const resolved: Record<string, SystemDepConfig> = {}
+	for (const [name, entry] of Object.entries(deps)) {
+		const builtin = catalog[name]
+		if (builtin === undefined) {
+			resolved[name] = entry as SystemDepConfig
+			continue
+		}
+		const version = typeof entry === "string" ? entry : entry.version
+		if (builtin.versions === "latest" && version !== "latest")
+			problems.push(`deps.${name}: ${name} only installs "latest"`)
+		if (builtin.versions === "pinned" && version === "latest") {
+			problems.push(`deps.${name}: ${name} needs a pinned version, not "latest"`)
+		}
+		resolved[name] = expand(builtin, entry as BuiltinOverride | string, arch as Arch, os)
+	}
+
+	/* prerequisites: add latest-only built-ins, name the fix for the rest */
+	const queue = Object.keys(resolved)
+	for (let i = 0; i < queue.length; i++) {
+		const name = queue[i] as string
+		for (const need of resolved[name]?.dependsOn ?? []) {
+			if (need in resolved) continue
+			const builtin = catalog[need]
+			if (builtin?.versions === "latest") {
+				resolved[need] = expand(builtin, "latest", arch as Arch, os)
+				queue.push(need)
+			} else if (builtin) {
+				problems.push(`deps.${name}: needs ${need}; add ${need}: "<version>"`)
+			}
+		}
+	}
+
+	if (problems.length > 0)
+		throw new ConfigError(`Invalid system config:\n${problems.map((p) => `  - ${p}`).join("\n")}`)
+	return resolved
+}

package/src/builtins/runtimes.ts

@@ -0,0 +1,54 @@
+/**
+ * JavaScript runtimes. bun is the package manager; node and deno are runtimes only.
+ */
+
+import { LOCAL_SHARE, pick, ps, tree, unix, winArchive, WIN_BIN, WIN_PROGRAMS, winTree } from "./recipes.ts"
+import type { BuiltinDep } from "./types.ts"
+
+export const RUNTIMES = {
+	bun: {
+		description: "Bun: runtime and the only package manager (its version also pins packageManager)",
+		env: (os) => [{ path: os === "windows" ? "$HOME\\.bun\\bin" : "$HOME/.bun/bin" }],
+		os: ({ version }) => ({
+			...unix(
+				`curl -fsSL https://bun.sh/install | bash -s "bun-v${version}"`,
+				`curl -fsSL https://bun.sh/install | bash -s "bun-v${version}"`,
+			),
+			windows: ps(`& ([scriptblock]::Create((irm https://bun.sh/install.ps1))) -Version ${version}`),
+		}),
+		versions: "pinned",
+	},
+	deno: {
+		description: "Deno, for the generated TypeScript SDK checks",
+		env: (os) => (os === "windows" ? [{ path: WIN_BIN }] : [{ path: "$HOME/.deno/bin" }]),
+		os: ({ version }) => {
+			const zip = `https://dl.deno.land/release/v${version}/deno-x86_64-pc-windows-msvc.zip`
+			return {
+				/* CI=1 keeps the installer from prompting for shell setup */
+				...unix(
+					`curl -fsSL https://deno.com/install.sh | CI=1 sh -s v${version}`,
+					`curl -fsSL https://deno.com/install.sh | CI=1 sh -s v${version}`,
+				),
+				windows: winArchive(zip, "deno.exe", "deno"),
+			}
+		},
+		versions: "pinned",
+	},
+	node: {
+		description: "Node.js runtime, for tools that need it (bun stays the package manager)",
+		env: (os) => [{ path: os === "windows" ? `${WIN_PROGRAMS}\\node` : `${LOCAL_SHARE}/node/bin` }],
+		os: ({ arch, version }) => {
+			const base = `https://nodejs.org/dist/v${version}/node-v${version}`
+			const a = pick(arch, { arm64: "arm64", x64: "x64" })
+			const dir = `${LOCAL_SHARE}/node`
+			return {
+				...unix(
+					tree(`${base}-linux-${a}.tar.xz`, dir, { nested: true }),
+					tree(`${base}-darwin-${a}.tar.gz`, dir, { nested: true }),
+				),
+				windows: winTree(`${base}-win-x64.zip`, `${WIN_PROGRAMS}\\node`, { nested: true }),
+			}
+		},
+		versions: "pinned",
+	},
+} satisfies Record<string, BuiltinDep>

package/src/builtins/types.ts

@@ -0,0 +1,38 @@
+import type { EnvVar, OsCommands, OsTarget, SystemDepConfig } from "../config.ts"
+
+/** CPU architectures built-ins ship recipes for. */
+export type Arch = "arm64" | "x64"
+
+export interface RecipeContext {
+	arch: Arch
+	version: string
+}
+
+/** A tool workerstack supports by name: the config gives a version, the catalog gives the rest. */
+export interface BuiltinDep {
+	/** `check` runs this; default `<name> --version` */
+	check?: SystemDepConfig["check"]
+	/** Other deps installed first. A `latest`-only built-in missing from the config is added; any other is an error. */
+	dependsOn?: readonly string[]
+	description: string
+	/** Shell env entries for the OS the config resolves on (PATH dirs differ between unix and Windows). */
+	env?: (os: OsTarget) => readonly EnvVar[]
+	/** Per-OS install commands for this version and CPU. */
+	os: (ctx: RecipeContext) => OsCommands
+	/**
+	 * `pinned`: needs an exact version, rejects `"latest"`. `latest`: only `"latest"` (the source cannot pin).
+	 * `any`: a pin or `"latest"`.
+	 */
+	versions: "any" | "latest" | "pinned"
+}
+
+/** The object form of a built-in entry: a version plus anything to override. `os` merges per key. */
+export interface BuiltinOverride {
+	check?: SystemDepConfig["check"]
+	dependsOn?: readonly string[]
+	description?: string
+	env?: readonly EnvVar[]
+	os?: OsCommands
+	required?: boolean
+	version: string
+}

package/src/commands/check.ts

@@ -0,0 +1,101 @@
+import { resolve } from "node:path"
+import { resolveOsCommand } from "../config.ts"
+import { versionsMatch } from "../version.ts"
+import { TTY_PATH_FALLBACK_WARN } from "../path.ts"
+import { type Context, probeInstalled } from "../probe.ts"
+import type { Runtime } from "../runtime.ts"
+
+/** `--here`: this process PATH. Otherwise a new interactive TTY's PATH, falling back with one warning. */
+function searchPath(rt: Runtime, here: boolean): string {
+	if (here) return rt.env.PATH ?? rt.env.Path ?? ""
+	const snapshot = rt.ttyPath()
+	if (snapshot.source === "process") rt.warn(`${TTY_PATH_FALLBACK_WARN} (${snapshot.reason})`)
+	return snapshot.path
+}
+
+/** Mismatch count from the packageManager field (0 or 1). bun is the only package manager. */
+function checkPackageManager(ctx: Context): number {
+	const bun = ctx.deps.bun
+	if (!bun) return 0
+	const { rt } = ctx
+	const pkg = JSON.parse(rt.readFile(resolve(ctx.configDir, ctx.packageJsonPath))) as { packageManager?: unknown }
+	const current = typeof pkg.packageManager === "string" ? pkg.packageManager : undefined
+
+	if (bun.version === "latest") {
+		if (current?.startsWith("bun@")) {
+			rt.log(`\n  v packageManager: ${current} (latest mode)`)
+			return 0
+		}
+		rt.log(`\n  ~ packageManager: ${current ?? "(missing)"} (expected bun@*)`)
+		return 1
+	}
+	const expected = `bun@${bun.version}`
+	if (current === expected) {
+		rt.log(`\n  v packageManager: ${current}`)
+		return 0
+	}
+	rt.log(`\n  ~ packageManager: ${current ?? "(missing)"} (expected ${expected})`)
+	return 1
+}
+
+export function checkCommand(ctx: Context, target: string | undefined, here: boolean): number {
+	const { rt } = ctx
+	const path = searchPath(rt, here)
+
+	if (target !== undefined) {
+		const config = ctx.deps[target]
+		if (!config) {
+			rt.error(`Unknown dependency: ${target}`)
+			rt.log(`Available: ${Object.keys(ctx.deps).join(", ")}`)
+			return 1
+		}
+		if (resolveOsCommand(target, config, ctx.os) === null) {
+			rt.log(`${target} — not available on ${ctx.os}`)
+			return 0
+		}
+		const installed = probeInstalled(rt, target, config, path)
+		if (!installed) {
+			rt.log(`${target} — not installed (expected ${config.version})`)
+			return 1
+		}
+		rt.log(`${target}@${installed.version} (expected ${config.version}) ${installed.path}`)
+		return 0
+	}
+
+	rt.log("@workerstack/system — check")
+	rt.log(`Detected OS: ${ctx.os}`)
+	rt.log("=".repeat(50))
+
+	let ok = 0
+	let mismatch = 0
+	let missing = 0
+	for (const [name, config] of Object.entries(ctx.deps)) {
+		const badge = config.required ? "[required]" : "[optional]"
+		if (resolveOsCommand(name, config, ctx.os) === null) {
+			rt.log(`  - ${badge} ${name} — not available on ${ctx.os}`)
+			continue
+		}
+		const installed = probeInstalled(rt, name, config, path)
+		if (!installed) {
+			rt.log(`  x ${badge} ${name} — not installed (expected ${config.version})`)
+			if (config.required) missing++
+			else mismatch++
+		} else if (versionsMatch(installed.version, config.version)) {
+			rt.log(`  v ${badge} ${name}@${installed.version}`)
+			ok++
+		} else {
+			rt.log(`  ~ ${badge} ${name}@${installed.version} (expected ${config.version}) ${installed.path}`)
+			mismatch++
+		}
+	}
+	mismatch += checkPackageManager(ctx)
+
+	rt.log(`\n${"=".repeat(50)}`)
+	rt.log(`OK: ${ok}  Mismatch: ${mismatch}  Missing: ${missing}`)
+	if (missing > 0) {
+		rt.log("\nRequired dependencies missing — run: system install")
+		return 1
+	}
+	rt.log(mismatch > 0 ? "\nVersion mismatches found — run: system install --upgrade" : "\nAll system dependencies OK")
+	return 0
+}

package/src/commands/env.ts

@@ -0,0 +1,99 @@
+import type { EnvVar } from "../config.ts"
+import {
+	applyEnvBlock,
+	type EnvLine,
+	expandPath,
+	hasEnvBlock,
+	reloadHint,
+	renderEnvBlock,
+	shellConfigPaths,
+	shellKind,
+} from "../env.ts"
+import type { Context } from "../probe.ts"
+import type { Runtime } from "../runtime.ts"
+
+/** The line `env` renders to, or null when a `detect` entry finds nothing and has no fallback. */
+function resolveEnvLine(rt: Runtime, env: EnvVar): EnvLine | null {
+	if ("path" in env) return { path: env.path }
+	if ("value" in env) return { key: env.key, value: env.value }
+	for (const path of env.detect) {
+		const expanded = expandPath(path, rt.home, rt.env)
+		if (rt.exists(expanded)) {
+			rt.log(`   Detected ${env.key} at: ${expanded}`)
+			return { key: env.key, value: path }
+		}
+	}
+	if (env.fallback !== undefined) {
+		rt.log(`   Using fallback for ${env.key}: ${env.fallback}`)
+		return { key: env.key, value: env.fallback }
+	}
+	rt.log(`   Could not detect ${env.key}, no fallback specified`)
+	return null
+}
+
+function rcFiles(rt: Runtime): { kind: ReturnType<typeof shellKind>; paths: string[] } {
+	const shell = rt.env.SHELL ?? ""
+	const kind = shellKind(rt.platform, shell)
+	return { kind, paths: shellConfigPaths(rt.home, kind, shell, rt.env) }
+}
+
+function fileName(path: string): string {
+	return path.split(/[\\/]/).pop() as string
+}
+
+/** Write `tool`'s managed block into the shell rc. True when a block was written. */
+export function configureEnvVars(rt: Runtime, tool: string, envVars: readonly EnvVar[]): boolean {
+	if (envVars.length === 0) return true
+
+	const { kind, paths } = rcFiles(rt)
+	const names = paths.map(fileName).join(", ")
+	rt.log(`\n   Configuring environment variables in ${names}...`)
+
+	const lines = envVars.map((env) => resolveEnvLine(rt, env)).filter((line) => line !== null)
+	if (lines.length === 0) {
+		rt.log("   No environment variables to configure")
+		return false
+	}
+
+	try {
+		for (const path of paths) {
+			const existing = rt.exists(path) ? rt.readFile(path) : ""
+			if (hasEnvBlock(existing, tool)) rt.log(`   Updating existing ${tool} environment config in ${fileName(path)}...`)
+			rt.writeFile(path, applyEnvBlock(existing, renderEnvBlock(tool, lines, kind), tool))
+		}
+	} catch (error) {
+		rt.error(`   Failed to configure env vars: ${error instanceof Error ? error.message : String(error)}`)
+		return false
+	}
+
+	rt.log(`   Added to ${names}:`)
+	for (const line of lines) rt.log("path" in line ? `      PATH=${line.path}:$PATH` : `      ${line.key}=${line.value}`)
+	rt.log(`\n   ${reloadHint(kind, paths[0] as string)}`)
+	return true
+}
+
+export function envCommand(ctx: Context): number {
+	const { rt } = ctx
+	rt.log("Setting up environment variables")
+	rt.log("=".repeat(50))
+
+	const envDeps = Object.entries(ctx.deps).flatMap(([tool, config]) =>
+		config.env && config.env.length > 0 ? [[tool, config.env] as const] : [],
+	)
+	if (envDeps.length === 0) {
+		rt.log("\nNo dependencies with environment variables configured.")
+		return 0
+	}
+
+	let failed = 0
+	for (const [tool, env] of envDeps) {
+		rt.log(`\n${tool}`)
+		if (!configureEnvVars(rt, tool, env)) failed++
+	}
+
+	const { kind, paths } = rcFiles(rt)
+	rt.log(`\n${"=".repeat(50)}`)
+	rt.log(`Environment variables configured in ${paths.join(", ")}`)
+	rt.log(`\n${reloadHint(kind, paths[0] as string)}`)
+	return failed > 0 ? 1 : 0
+}

package/src/commands/install.ts

@@ -0,0 +1,134 @@
+import { resolveOsCommand, type SystemDepConfig } from "../config.ts"
+import { versionsMatch } from "../version.ts"
+import { sortByDependencies } from "../graph.ts"
+import { type Context, probeInstalled } from "../probe.ts"
+import { expandPath } from "../env.ts"
+import { configureEnvVars } from "./env.ts"
+
+export interface InstallOptions {
+	dryRun: boolean
+	upgrade: boolean
+}
+
+type Outcome = "failed" | "installed" | "planned" | "skipped" | "unavailable"
+
+/**
+ * Write the dep's env block whenever it is present, installed now or before: an already-installed tool
+ * (a CI image's rust, a setup action's bun) is otherwise missing from a new shell's PATH.
+ */
+function writeEnv(ctx: Context, name: string, config: SystemDepConfig): void {
+	if (config.env && config.env.length > 0) configureEnvVars(ctx.rt, name, config.env)
+}
+
+function installOne(ctx: Context, name: string, config: SystemDepConfig, opts: InstallOptions): Outcome {
+	const { rt } = ctx
+	const command = resolveOsCommand(name, config, ctx.os)
+	if (!command) {
+		rt.log(`${name}@${config.version} — not available on ${ctx.os}`)
+		return "unavailable"
+	}
+
+	rt.log(`${name}@${config.version}`)
+	rt.log(`   ${config.description}`)
+
+	if (opts.dryRun) {
+		rt.log(`   dry-run: ${command}`)
+		return "planned"
+	}
+
+	const installed = probeInstalled(rt, name, config)
+	if (installed && versionsMatch(installed.version, config.version)) {
+		rt.log(`   Already installed (${installed.version}), skipping`)
+		writeEnv(ctx, name, config)
+		return "skipped"
+	}
+	if (installed && !opts.upgrade) {
+		rt.log(`   Already installed (${installed.version}), skipping (expected ${config.version}) ${installed.path}`)
+		rt.log(`   run: system install ${name} --upgrade`)
+		writeEnv(ctx, name, config)
+		return "skipped"
+	}
+
+	if (!rt.run(command)) {
+		rt.error(`\nCommand failed: ${command}`)
+		rt.error("   Installation failed")
+		return "failed"
+	}
+
+	rt.log("   Installed successfully")
+	writeEnv(ctx, name, config)
+	/* Installer often does not win PATH — brew/nvm/fnm still first. */
+	const after = probeInstalled(rt, name, config)
+	if (after && !versionsMatch(after.version, config.version)) {
+		rt.log(`   PATH still has ${after.version} (expected ${config.version}) ${after.path}`)
+		rt.log("   Unpin/unlink that binary or put the pinned one first on PATH")
+	}
+	return "installed"
+}
+
+/**
+ * Put every dep's `{ path }` dirs first on this run's PATH, so a dep finds a prerequisite installed earlier
+ * in the same run (ruff needs uv) and the skip check sees the pinned binary before a system one.
+ */
+function prependDepPaths(ctx: Context): void {
+	for (const config of Object.values(ctx.deps)) {
+		for (const entry of config.env ?? []) {
+			if ("path" in entry) ctx.rt.prependPath(expandPath(entry.path, ctx.rt.home, ctx.rt.env))
+		}
+	}
+}
+
+export function installCommand(ctx: Context, target: string | undefined, opts: InstallOptions): number {
+	const { rt } = ctx
+	prependDepPaths(ctx)
+
+	if (target !== undefined) {
+		const config = ctx.deps[target]
+		if (!config) {
+			rt.error(`Unknown dependency: ${target}`)
+			rt.log(`Available: ${Object.keys(ctx.deps).join(", ")}`)
+			return 1
+		}
+		rt.log(`Detected OS: ${ctx.os}`)
+		return installOne(ctx, target, config, opts) === "failed" ? 1 : 0
+	}
+
+	rt.log("@workerstack/system — install")
+	rt.log(`Detected OS: ${ctx.os}`)
+	rt.log("=".repeat(50))
+
+	const entries = sortByDependencies(Object.entries(ctx.deps))
+	rt.log(`\nFound ${entries.length} dependencies to install:\n`)
+	for (const [name, config] of entries) {
+		const badge = config.required ? "[required]" : "[optional]"
+		const available = resolveOsCommand(name, config, ctx.os) !== null
+		rt.log(`  ${badge} ${name}@${config.version}${available ? "" : ` (not available on ${ctx.os})`}`)
+	}
+
+	rt.log(`\n${"=".repeat(50)}`)
+	rt.log(opts.dryRun ? "Dry-run — commands only, nothing installed" : "Installing dependencies...")
+	rt.log("=".repeat(50))
+
+	const counts: Record<Outcome, number> = { failed: 0, installed: 0, planned: 0, skipped: 0, unavailable: 0 }
+	for (const [name, config] of entries) {
+		const outcome = installOne(ctx, name, config, opts)
+		/* an optional dep that fails does not fail the run */
+		counts[outcome === "failed" && !config.required ? "skipped" : outcome]++
+	}
+
+	rt.log(`\n${"=".repeat(50)}`)
+	rt.log("Installation Summary")
+	rt.log("=".repeat(50))
+	if (opts.dryRun) rt.log(`Planned: ${counts.planned}`)
+	else rt.log(`Installed: ${counts.installed}`)
+	rt.log(`Skipped: ${counts.skipped}`)
+	rt.log(`Unavailable on ${ctx.os}: ${counts.unavailable}`)
+	rt.log(`Failed: ${counts.failed}`)
+
+	if (counts.failed > 0) {
+		rt.log("\nSome required dependencies failed to install")
+		return 1
+	}
+	rt.log(opts.dryRun ? "\nDry-run complete" : "\nAll required system dependencies are ready!")
+	return 0
+}

package/src/commands/list.ts

@@ -0,0 +1,29 @@
+import type { BuiltinDep } from "../builtins/types.ts"
+import { OS_TARGETS } from "../config.ts"
+import type { Runtime } from "../runtime.ts"
+
+/** The OS targets a built-in has a command for. */
+function availability(builtin: BuiltinDep): string {
+	const os = builtin.os({ arch: "x64", version: builtin.versions === "latest" ? "latest" : "0.0.0" })
+	return OS_TARGETS.filter((target) => {
+		const command = os[target] ?? os.all
+		return typeof command === "string"
+	}).join(" ")
+}
+
+/** Print the built-in catalog: name, version policy, where it installs, what it is. */
+export function listCommand(rt: Runtime, catalog: Readonly<Record<string, BuiltinDep>>): number {
+	const rows = Object.entries(catalog).map(([name, builtin]) => [
+		name,
+		builtin.versions,
+		availability(builtin),
+		builtin.description,
+	])
+	const widths = [0, 1, 2].map((col) => Math.max(...rows.map((row) => (row[col] as string).length)))
+	rt.log('Built-in deps (give a version: go: "1.27.2")')
+	rt.log("")
+	for (const row of rows) {
+		rt.log(`  ${row.map((cell, col) => (col < 3 ? cell.padEnd(widths[col] as number) : cell)).join("  ")}`)
+	}
+	return 0
+}