@workerstack/system 0.0.0-stage → 0.3.0

package/src/builtins/browsers.ts

@@ -0,0 +1,79 @@
+/**
+ * Containers and browsers: docker, chromium, lightpanda, playwright.
+ */
+
+import { binary, LOCAL_BIN, localBinEnv, pick } from "./recipes.ts"
+import type { BuiltinDep } from "./types.ts"
+
+/**
+ * Prints the version only when Playwright's Chromium is on disk. `bunx playwright@<v> --version` alone
+ * always succeeds (bunx fetches the CLI), which would make `install` skip the browser download.
+ */
+const PLAYWRIGHT_CHECK =
+	"bun -e \"const r=Bun.spawnSync(['bunx','playwright@{{version}}','install','--dry-run','chromium']);" +
+	"const m=r.stdout.toString().match(/Install location:\\s*(.+)/);" +
+	"if(m&&require('fs').existsSync(m[1].trim()))console.log('{{version}}');else process.exit(1)\""
+
+export const BROWSERS = {
+	chromium: {
+		description: "Chromium, the browser rail fallback (Linux only: brew and choco ship no usable build)",
+		env: localBinEnv,
+		os: () => ({
+			"linux-apt": "sudo apt-get install -y chromium || sudo snap install chromium",
+			/* Fedora names the binary chromium-browser; link the name check and the browser rail use */
+			"linux-dnf": `sudo dnf install -y chromium && mkdir -p "${LOCAL_BIN}" && ln -sf /usr/bin/chromium-browser "${LOCAL_BIN}/chromium"`,
+			"linux-pacman": "sudo pacman -S --noconfirm chromium",
+			macos: false,
+			windows: false,
+		}),
+		versions: "latest",
+	},
+	docker: {
+		dependsOn: ["brew", "choco"],
+		description: "Container engine with its daemon (Docker Engine on Linux, Docker Desktop elsewhere)",
+		os: () => ({
+			"linux-apt": 'curl -fsSL https://get.docker.com | sudo sh && sudo usermod -aG docker "$USER"',
+			"linux-dnf": 'curl -fsSL https://get.docker.com | sudo sh && sudo usermod -aG docker "$USER"',
+			"linux-pacman":
+				'sudo pacman -S --noconfirm docker docker-buildx docker-compose && sudo systemctl enable --now docker.service && sudo usermod -aG docker "$USER"',
+			macos: "brew install --cask docker-desktop",
+			windows: "choco install docker-desktop -y",
+		}),
+		versions: "latest",
+	},
+	lightpanda: {
+		check: { command: "lightpanda version" },
+		description: "Lightpanda, the default headless browser rail (nightly; no Windows build)",
+		env: localBinEnv,
+		os: ({ arch }) => {
+			const base = "https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda"
+			const cpu = pick(arch, { arm64: "aarch64", x64: "x86_64" })
+			const linux = binary(`${base}-${cpu}-linux`, "lightpanda")
+			return {
+				"linux-apt": linux,
+				"linux-dnf": linux,
+				"linux-pacman": linux,
+				macos: binary(`${base}-${cpu}-macos`, "lightpanda"),
+				windows: false,
+			}
+		},
+		versions: "latest",
+	},
+	playwright: {
+		check: { command: PLAYWRIGHT_CHECK },
+		dependsOn: ["bun"],
+		description: "Playwright's Chromium for browser tests (version = your @playwright/test)",
+		os: ({ version }) => {
+			const browserOnly = `bunx playwright@${version} install chromium`
+			return {
+				/* --with-deps installs the shared libraries through apt; other distros only get the browser */
+				"linux-apt": `bunx playwright@${version} install --with-deps chromium`,
+				"linux-dnf": browserOnly,
+				"linux-pacman": browserOnly,
+				macos: browserOnly,
+				windows: browserOnly,
+			}
+		},
+		versions: "pinned",
+	},
+} satisfies Record<string, BuiltinDep>

package/src/builtins/cloudflare.ts

@@ -0,0 +1,32 @@
+/**
+ * Cloudflare: the cf CLI and the cloudflared tunnel client.
+ */
+
+import { archive, binary, bunGlobal, localBinEnv, pick, unix, winBinary } from "./recipes.ts"
+import type { BuiltinDep } from "./types.ts"
+
+export const CLOUDFLARE = {
+	cf: {
+		/* installed by bun; its launcher is a node script */
+		dependsOn: ["bun", "node"],
+		description: "Cloudflare CLI: deploy, workers types, account operations (bun global, runs on node)",
+		os: ({ version }) => bunGlobal("cf", version),
+		versions: "pinned",
+	},
+	cloudflared: {
+		description: "Cloudflare Tunnel client, for remote bindings",
+		env: localBinEnv,
+		os: ({ arch, version }) => {
+			const base = `https://github.com/cloudflare/cloudflared/releases/download/${version}/cloudflared`
+			const a = pick(arch, { arm64: "arm64", x64: "amd64" })
+			return {
+				...unix(
+					binary(`${base}-linux-${a}`, "cloudflared"),
+					archive(`${base}-darwin-${a}.tgz`, "cloudflared", "cloudflared"),
+				),
+				windows: winBinary(`${base}-windows-amd64.exe`, "cloudflared"),
+			}
+		},
+		versions: "pinned",
+	},
+} satisfies Record<string, BuiltinDep>

package/src/builtins/database.ts

@@ -0,0 +1,41 @@
+/**
+ * Database tooling: Atlas migrations and the libSQL server.
+ */
+
+import { archive, binary, localBinEnv, pick, unix, winBinary } from "./recipes.ts"
+import type { BuiltinDep } from "./types.ts"
+
+export const DATABASE = {
+	atlas: {
+		check: { command: "atlas version" },
+		description: "Atlas schema migrations",
+		env: localBinEnv,
+		os: ({ arch, version }) => {
+			const base = "https://release.ariga.io/atlas/atlas"
+			const a = pick(arch, { arm64: "arm64", x64: "amd64" })
+			return {
+				...unix(binary(`${base}-linux-${a}-v${version}`, "atlas"), binary(`${base}-darwin-${a}-v${version}`, "atlas")),
+				windows: winBinary(`${base}-windows-amd64-v${version}.exe`, "atlas"),
+			}
+		},
+		versions: "pinned",
+	},
+	sqld: {
+		description: "libSQL server, for local database tests (no Windows build)",
+		env: localBinEnv,
+		os: ({ arch, version }) => {
+			const base = `https://github.com/tursodatabase/libsql/releases/download/libsql-server-v${version}/libsql-server`
+			const cpu = pick(arch, { arm64: "aarch64", x64: "x86_64" })
+			const linux = `${cpu}-unknown-linux-gnu`
+			const mac = `${cpu}-apple-darwin`
+			return {
+				...unix(
+					archive(`${base}-${linux}.tar.xz`, `libsql-server-${linux}/sqld`, "sqld"),
+					archive(`${base}-${mac}.tar.xz`, `libsql-server-${mac}/sqld`, "sqld"),
+				),
+				windows: false,
+			}
+		},
+		versions: "pinned",
+	},
+} satisfies Record<string, BuiltinDep>

package/src/builtins/index.ts

@@ -0,0 +1,41 @@
+/**
+ * The built-in catalog: every tool workerstack supports by name. A config gives `name: "<version>"`;
+ * the catalog supplies the install commands, check, env and prerequisites.
+ */
+
+import { AGENTS } from "./agents.ts"
+import { BOOTSTRAP } from "./bootstrap.ts"
+import { BROWSERS } from "./browsers.ts"
+import { CLOUDFLARE } from "./cloudflare.ts"
+import { DATABASE } from "./database.ts"
+import { LANGUAGES } from "./languages.ts"
+import { RELEASE } from "./release.ts"
+import { RUNTIMES } from "./runtimes.ts"
+import type { BuiltinDep } from "./types.ts"
+
+/** The catalog by group, for docs and per-group CI installs. */
+export const BUILTIN_GROUPS = {
+	bootstrap: BOOTSTRAP,
+	runtimes: RUNTIMES,
+	languages: LANGUAGES,
+	release: RELEASE,
+	cloudflare: CLOUDFLARE,
+	database: DATABASE,
+	browsers: BROWSERS,
+	agents: AGENTS,
+} as const
+
+export const BUILTINS = {
+	...BOOTSTRAP,
+	...RUNTIMES,
+	...LANGUAGES,
+	...RELEASE,
+	...CLOUDFLARE,
+	...DATABASE,
+	...BROWSERS,
+	...AGENTS,
+} satisfies Record<string, BuiltinDep>
+
+export type BuiltinName = keyof typeof BUILTINS
+
+export const BUILTIN_NAMES: ReadonlySet<string> = new Set(Object.keys(BUILTINS))

package/src/builtins/languages.ts

@@ -0,0 +1,218 @@
+/**
+ * Every language the generated clients target: Go, Rust, Python, C#, Java, with their formatters.
+ * (TypeScript runs on bun, in the runtimes group.)
+ */
+
+import type { OsTarget } from "../config.ts"
+import {
+	binary,
+	LOCAL_BIN,
+	LOCAL_SHARE,
+	localBinEnv,
+	pick,
+	ps,
+	tree,
+	unix,
+	WIN_PROGRAMS,
+	winBinary,
+	winPathDir,
+	winTree,
+} from "./recipes.ts"
+import type { Arch, BuiltinDep } from "./types.ts"
+
+/** uv puts Python and tool shims in `~/.local/bin` (`%USERPROFILE%\.local\bin` on Windows). */
+function uvBinEnv(os: OsTarget) {
+	return [{ path: os === "windows" ? "$HOME\\.local\\bin" : LOCAL_BIN }]
+}
+
+/**
+ * A uv command whose shims land in the bin dir `uvBinEnv` puts on PATH. On unix uv derives that dir from
+ * XDG_BIN_HOME / XDG_DATA_HOME, which can point anywhere, so the dir is named explicitly.
+ */
+function uvCommand(variable: "UV_PYTHON_BIN_DIR" | "UV_TOOL_BIN_DIR", command: string) {
+	const pinned = `${variable}="${LOCAL_BIN}" ${command}`
+	return { ...unix(pinned, pinned), windows: command }
+}
+
+/** Adoptium download for a feature major (`21`, latest GA) or an exact release (`21.0.13+9`). */
+function temurin(version: string, os: "linux" | "mac" | "windows", arch: Arch): string {
+	const api = "https://api.adoptium.net/v3/binary"
+	const a = pick(arch, { arm64: "aarch64", x64: "x64" })
+	const tail = `${os}/${a}/jdk/hotspot/normal/eclipse`
+	return /^\d+$/.test(version)
+		? `${api}/latest/${version}/ga/${tail}`
+		: `${api}/version/jdk-${encodeURIComponent(version)}/${tail}`
+}
+
+const JAVA_DIR = `${LOCAL_SHARE}/java`
+/** macOS JDKs keep their home under Contents/Home. */
+const javaHome = (os: OsTarget) =>
+	os === "windows" ? `${WIN_PROGRAMS}\\java` : os === "macos" ? `${JAVA_DIR}/Contents/Home` : JAVA_DIR
+
+const GJF_JAR = `${LOCAL_SHARE}/google-java-format/google-java-format.jar`
+
+export const LANGUAGES = {
+	dotnet: {
+		description: ".NET SDK, for the generated C# SDK (dotnet format included)",
+		env: (os) => {
+			const dir = os === "windows" ? `${WIN_PROGRAMS}\\dotnet` : `${LOCAL_SHARE}/dotnet`
+			return [{ key: "DOTNET_ROOT", value: dir }, { path: dir }]
+		},
+		os: ({ version }) => {
+			const sh = `curl -fsSL https://dot.net/v1/dotnet-install.sh | bash -s -- --version ${version} --install-dir "${LOCAL_SHARE}/dotnet" --no-path`
+			return {
+				...unix(sh, sh),
+				/* Fedora images lack the ICU library .NET needs at startup */
+				"linux-dnf": `sudo dnf install -y libicu && ${sh}`,
+				windows: ps(
+					'$s = Join-Path $env:TEMP "dotnet-install.ps1"',
+					"Invoke-WebRequest -UseBasicParsing https://dot.net/v1/dotnet-install.ps1 -OutFile $s",
+					`& $s -Version ${version} -InstallDir "${WIN_PROGRAMS}\\dotnet" -NoPath`,
+					winPathDir(`${WIN_PROGRAMS}\\dotnet`),
+				),
+			}
+		},
+		versions: "pinned",
+	},
+	go: {
+		check: { command: "go version", pattern: "go(\\d+\\.\\d+(?:\\.\\d+)?)" },
+		description: "Go toolchain (gofmt included), for the generated Go SDK and CLI",
+		env: (os) =>
+			os === "windows"
+				? [{ path: `${WIN_PROGRAMS}\\go\\bin` }, { path: "$HOME\\go\\bin" }]
+				: [{ path: `${LOCAL_SHARE}/go/bin` }, { path: "$HOME/go/bin" }],
+		os: ({ arch, version }) => {
+			const base = `https://go.dev/dl/go${version}`
+			const a = pick(arch, { arm64: "arm64", x64: "amd64" })
+			const dir = `${LOCAL_SHARE}/go`
+			return {
+				...unix(
+					tree(`${base}.linux-${a}.tar.gz`, dir, { nested: true }),
+					tree(`${base}.darwin-${a}.tar.gz`, dir, { nested: true }),
+				),
+				windows: winTree(`${base}.windows-amd64.zip`, `${WIN_PROGRAMS}\\go`, { bin: "bin", nested: true }),
+			}
+		},
+		versions: "pinned",
+	},
+	"google-java-format": {
+		check: { command: "google-java-format --version 2>&1" },
+		dependsOn: ["java"],
+		description: "google-java-format, the generated Java SDK's formatter",
+		env: localBinEnv,
+		os: ({ arch, version }) => {
+			const base = `https://github.com/google/google-java-format/releases/download/v${version}`
+			/* no native macOS x64 build: run the all-deps jar on the java dep */
+			const jar = [
+				`mkdir -p "$(dirname "${GJF_JAR}")" "${LOCAL_BIN}"`,
+				`curl -fsSL "${base}/google-java-format-${version}-all-deps.jar" -o "${GJF_JAR}"`,
+				`printf '#!/bin/sh\\nexec java -jar "${GJF_JAR}" "$@"\\n' > "${LOCAL_BIN}/google-java-format"`,
+				`chmod +x "${LOCAL_BIN}/google-java-format"`,
+			].join(" && ")
+			return {
+				...unix(
+					binary(
+						`${base}/google-java-format_linux-${pick(arch, { arm64: "arm64", x64: "x86-64" })}`,
+						"google-java-format",
+					),
+					arch === "arm64" ? binary(`${base}/google-java-format_darwin-arm64`, "google-java-format") : jar,
+				),
+				windows: winBinary(`${base}/google-java-format_windows-x86-64.exe`, "google-java-format"),
+			}
+		},
+		versions: "pinned",
+	},
+	gradle: {
+		check: { command: "gradle --version", pattern: "Gradle (\\d+\\.\\d+(?:\\.\\d+)?)" },
+		dependsOn: ["java"],
+		description: "Gradle, the generated Java SDK's build",
+		env: (os) => [{ path: os === "windows" ? `${WIN_PROGRAMS}\\gradle\\bin` : `${LOCAL_SHARE}/gradle/bin` }],
+		os: ({ version }) => {
+			const zip = `https://services.gradle.org/distributions/gradle-${version}-bin.zip`
+			const sh = tree(zip, `${LOCAL_SHARE}/gradle`, { nested: true })
+			return {
+				...unix(sh, sh),
+				windows: winTree(zip, `${WIN_PROGRAMS}\\gradle`, { bin: "bin", nested: true }),
+			}
+		},
+		versions: "pinned",
+	},
+	java: {
+		/* `java -version` prints to stderr; the build line carries the full release (21.0.13+9) */
+		check: { command: "java -version 2>&1", pattern: "build (\\d+[\\d.]*\\+\\d+)" },
+		description: "Eclipse Temurin JDK: a feature major (21) or an exact release (21.0.13+9)",
+		env: (os) => [
+			{ key: "JAVA_HOME", value: javaHome(os) },
+			{ path: os === "windows" ? `${javaHome(os)}\\bin` : `${javaHome(os)}/bin` },
+		],
+		os: ({ arch, version }) => ({
+			...unix(
+				tree(temurin(version, "linux", arch), JAVA_DIR, { nested: true }),
+				tree(temurin(version, "mac", arch), JAVA_DIR, { nested: true }),
+			),
+			windows: winTree(temurin(version, "windows", arch), `${WIN_PROGRAMS}\\java`, { bin: "bin", nested: true }),
+		}),
+		versions: "pinned",
+	},
+	mypy: {
+		dependsOn: ["uv"],
+		description: "mypy, the generated Python SDK's type check (uv tool)",
+		env: uvBinEnv,
+		os: ({ version }) => uvCommand("UV_TOOL_BIN_DIR", `uv tool install --force mypy==${version}`),
+		versions: "pinned",
+	},
+	python: {
+		check: { command: "python --version" },
+		dependsOn: ["uv"],
+		description: "Python, managed by uv (python and python3 shims)",
+		env: uvBinEnv,
+		os: ({ version }) => uvCommand("UV_PYTHON_BIN_DIR", `uv python install ${version} --default`),
+		versions: "pinned",
+	},
+	ruff: {
+		dependsOn: ["uv"],
+		description: "ruff, the generated Python SDK's formatter and linter (uv tool)",
+		env: uvBinEnv,
+		os: ({ version }) => uvCommand("UV_TOOL_BIN_DIR", `uv tool install --force ruff==${version}`),
+		versions: "pinned",
+	},
+	rust: {
+		check: { command: "rustc --version" },
+		description: "Rust via rustup (rustfmt and clippy), for the generated Rust SDK",
+		env: (os) => [{ path: os === "windows" ? "$HOME\\.cargo\\bin" : "$HOME/.cargo/bin" }],
+		os: ({ arch, version }) => {
+			const flags = `-y --default-toolchain ${version} --profile minimal -c rustfmt -c clippy`
+			return {
+				...unix(
+					`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- ${flags} --no-modify-path`,
+					`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- ${flags} --no-modify-path`,
+				),
+				/* rustup-init adds cargo\bin to the user PATH itself on Windows */
+				windows: ps(
+					'$r = Join-Path $env:TEMP "rustup-init.exe"',
+					`Invoke-WebRequest -UseBasicParsing "https://static.rust-lang.org/rustup/dist/${pick(arch, { arm64: "aarch64", x64: "x86_64" })}-pc-windows-msvc/rustup-init.exe" -OutFile $r`,
+					`& $r ${flags}`,
+					"if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }",
+				),
+			}
+		},
+		versions: "pinned",
+	},
+	uv: {
+		description: "uv, the Python toolchain manager",
+		env: localBinEnv,
+		os: ({ version }) => ({
+			...unix(
+				`curl -LsSf https://astral.sh/uv/${version}/install.sh | env UV_INSTALL_DIR="${LOCAL_BIN}" UV_NO_MODIFY_PATH=1 sh`,
+				`curl -LsSf https://astral.sh/uv/${version}/install.sh | env UV_INSTALL_DIR="${LOCAL_BIN}" UV_NO_MODIFY_PATH=1 sh`,
+			),
+			windows: ps(
+				winPathDir("$env:LOCALAPPDATA\\bin"),
+				'$env:UV_INSTALL_DIR = "$env:LOCALAPPDATA\\bin"',
+				'$env:UV_NO_MODIFY_PATH = "1"',
+				`irm https://astral.sh/uv/${version}/install.ps1 | iex`,
+			),
+		}),
+		versions: "pinned",
+	},
+} satisfies Record<string, BuiltinDep>

package/src/builtins/recipes.ts

@@ -0,0 +1,145 @@
+/**
+ * Building blocks for built-in install commands. Unix installs land in `$HOME/.local/bin` (or a tool dir
+ * under `$HOME/.local/share`) without sudo; Windows installs land in `%LOCALAPPDATA%\bin` (or a tool dir
+ * under `%LOCALAPPDATA%\Programs`), which the command adds to the user PATH.
+ */
+
+import type { EnvVar, OsCommands, OsTarget } from "../config.ts"
+import type { Arch } from "./types.ts"
+
+export const LOCAL_BIN = "$HOME/.local/bin"
+export const LOCAL_SHARE = "$HOME/.local/share"
+export const WIN_BIN = "$env:LOCALAPPDATA\\bin"
+export const WIN_PROGRAMS = "$env:LOCALAPPDATA\\Programs"
+
+/** The same command on every Linux distro, and one for macOS. */
+export function unix(linux: string, macos: string): OsCommands {
+	return { "linux-apt": linux, "linux-dnf": linux, "linux-pacman": linux, macos }
+}
+
+/**
+ * A global JS CLI through bun, the only package manager. On unix bun derives its global bin dir from
+ * XDG_CACHE_HOME when set, so the dir bun's env block puts on PATH is named explicitly.
+ */
+export function bunGlobal(pkg: string, version: string): OsCommands {
+	const command = `bun i -g ${pkg}@${version}`
+	const pinned = `BUN_INSTALL_BIN="$HOME/.bun/bin" ${command}`
+	return { ...unix(pinned, pinned), windows: command }
+}
+
+/** The value for this CPU. */
+export function pick<T>(arch: Arch, values: { arm64: T; x64: T }): T {
+	return values[arch]
+}
+
+/** Download one executable into `$HOME/.local/bin/<name>`. */
+export function binary(url: string, name: string): string {
+	return `mkdir -p "${LOCAL_BIN}" && curl -fsSL "${url}" -o "${LOCAL_BIN}/${name}" && chmod +x "${LOCAL_BIN}/${name}"`
+}
+
+/** Unpack `$tmp/archive` into `$tmp/x`: unzip for .zip (GNU tar cannot), tar otherwise. */
+function extract(url: string): string {
+	if (url.endsWith(".zip")) return 'unzip -q "$tmp/archive" -d "$tmp/x"'
+	const flag = /\.(tar\.gz|tgz)$/.test(url) ? "z" : url.endsWith(".tar.xz") ? "J" : ""
+	return `tar -x${flag}f "$tmp/archive" -C "$tmp/x"`
+}
+
+function download(url: string): string[] {
+	return ['tmp="$(mktemp -d)"', `curl -fsSL "${url}" -o "$tmp/archive"`, 'mkdir "$tmp/x"', extract(url)]
+}
+
+const CLEANUP = 'rm -rf "$tmp"'
+
+/** Download an archive and install `member` (a path inside it) as `$HOME/.local/bin/<name>`. */
+export function archive(url: string, member: string, name: string): string {
+	return [
+		...download(url),
+		`mkdir -p "${LOCAL_BIN}"`,
+		`install -m 755 "$tmp/x/${member}" "${LOCAL_BIN}/${name}"`,
+		CLEANUP,
+	].join(" && ")
+}
+
+/**
+ * Unpack a whole archive into `dir` (replacing it), for tools that need their files next to the binary.
+ * `nested`: the archive holds one top folder (`go/`, `node-v24.21.0-linux-x64/`), which becomes `dir`.
+ * Each of `bins` (a path inside `dir`) is linked into `$HOME/.local/bin`.
+ */
+export function tree(url: string, dir: string, opts: { bins?: readonly string[]; nested?: boolean } = {}): string {
+	const links = (opts.bins ?? []).map((bin) => `ln -sf "${dir}/${bin}" "${LOCAL_BIN}/${bin.split("/").pop()}"`)
+	return [
+		...download(url),
+		`rm -rf "${dir}"`,
+		`mkdir -p "$(dirname "${dir}")" "${LOCAL_BIN}"`,
+		opts.nested ? `mv "$tmp"/x/* "${dir}"` : `mv "$tmp/x" "${dir}"`,
+		...links,
+		CLEANUP,
+	].join(" && ")
+}
+
+/** Stop on the first error and skip the progress bar (it slows Invoke-WebRequest badly). */
+const PS_PRELUDE = "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue'"
+
+/** Make `dir` exist and be on the user PATH. */
+export function winPathDir(dir: string): string {
+	return [
+		`$d = "${dir}"`,
+		"New-Item -ItemType Directory -Force $d | Out-Null",
+		'$u = [Environment]::GetEnvironmentVariable("Path", "User")',
+		'if (-not (($u -split ";") -contains $d)) { [Environment]::SetEnvironmentVariable("Path", "$d;$u", "User") }',
+	].join("; ")
+}
+
+/** Download one .exe into `%LOCALAPPDATA%\bin\<name>.exe`. */
+export function winBinary(url: string, name: string): string {
+	return [
+		PS_PRELUDE,
+		winPathDir(WIN_BIN),
+		`Invoke-WebRequest -UseBasicParsing "${url}" -OutFile "${WIN_BIN}\\${name}.exe"`,
+	].join("; ")
+}
+
+const WIN_TEMP = ["$t = Join-Path $env:TEMP ([guid]::NewGuid())", "New-Item -ItemType Directory $t | Out-Null"]
+
+/** Download a zip and copy `member` (a path inside it) to `%LOCALAPPDATA%\bin\<name>.exe`. */
+export function winArchive(url: string, member: string, name: string): string {
+	return [
+		PS_PRELUDE,
+		winPathDir(WIN_BIN),
+		...WIN_TEMP,
+		`Invoke-WebRequest -UseBasicParsing "${url}" -OutFile "$t\\archive.zip"`,
+		'Expand-Archive "$t\\archive.zip" "$t\\x"',
+		`Copy-Item "$t\\x\\${member}" "${WIN_BIN}\\${name}.exe" -Force`,
+		"Remove-Item -Recurse -Force $t",
+	].join("; ")
+}
+
+/**
+ * Unpack a whole zip into `dir` (replacing it) and put `dir\<bin>` on the user PATH.
+ * `nested`: the zip holds one top folder, which becomes `dir`.
+ */
+export function winTree(url: string, dir: string, opts: { bin?: string; nested?: boolean } = {}): string {
+	return [
+		PS_PRELUDE,
+		...WIN_TEMP,
+		`Invoke-WebRequest -UseBasicParsing "${url}" -OutFile "$t\\archive.zip"`,
+		'Expand-Archive "$t\\archive.zip" "$t\\x"',
+		`if (Test-Path "${dir}") { Remove-Item -Recurse -Force "${dir}" }`,
+		`New-Item -ItemType Directory -Force (Split-Path "${dir}") | Out-Null`,
+		opts.nested
+			? `Move-Item (Get-ChildItem "$t\\x" -Directory | Select-Object -First 1).FullName "${dir}"`
+			: `Move-Item "$t\\x" "${dir}"`,
+		"Remove-Item -Recurse -Force $t",
+		winPathDir(opts.bin ? `${dir}\\${opts.bin}` : dir),
+	].join("; ")
+}
+
+/** A Windows command run in PowerShell with the stop-on-error prelude. */
+export function ps(...steps: string[]): string {
+	return [PS_PRELUDE, ...steps].join("; ")
+}
+
+/** PATH entries for a tool in the per-user bin dirs: `$HOME/.local/bin` on unix, `%LOCALAPPDATA%\bin` on Windows. */
+export function localBinEnv(os: OsTarget): EnvVar[] {
+	return [{ path: os === "windows" ? WIN_BIN : LOCAL_BIN }]
+}