@workerstack/system 0.0.0-stage → 0.3.0

package/src/commands/sync-pm.ts

@@ -0,0 +1,53 @@
+import { resolve } from "node:path"
+import type { Context } from "../probe.ts"
+
+/**
+ * `json` with `packageManager` set to `value`, keeping the file's indent, EOL, trailing newline and key
+ * order. A new field goes right after `name`, or first when there is no `name`.
+ */
+export function withPackageManager(json: string, path: string, value: string): string {
+	const pkg: unknown = JSON.parse(json)
+	if (typeof pkg !== "object" || pkg === null || Array.isArray(pkg)) throw new Error(`${path} is not a JSON object`)
+
+	const entries = Object.entries(pkg).filter(([key]) => key !== "packageManager")
+	const existing = Object.keys(pkg).indexOf("packageManager")
+	const at = existing !== -1 ? existing : entries.findIndex(([key]) => key === "name") + 1
+	entries.splice(at, 0, ["packageManager", value])
+
+	const indent = json.match(/^[ \t]+(?=")/m)?.[0] ?? ""
+	const eol = json.includes("\r\n") ? "\r\n" : "\n"
+	const body = JSON.stringify(Object.fromEntries(entries), null, indent).replace(/\n/g, eol)
+	return json.endsWith("\n") ? body + eol : body
+}
+
+/** Set package.json `packageManager` to `bun@<deps.bun.version>`. bun is the only package manager. */
+export function syncPmCommand(ctx: Context): number {
+	const { rt } = ctx
+	const bun = ctx.deps.bun
+	if (!bun) {
+		rt.log("\nSkipping packageManager sync — bun not in config")
+		return 0
+	}
+	if (bun.version === "latest") {
+		rt.log('\nSkipping packageManager sync — bun version is "latest"')
+		return 0
+	}
+
+	const path = resolve(ctx.configDir, ctx.packageJsonPath)
+	const expected = `bun@${bun.version}`
+	try {
+		const content = rt.readFile(path)
+		const current = (JSON.parse(content) as { packageManager?: unknown }).packageManager
+		if (current === expected) {
+			rt.log(`\npackageManager already correct: ${expected}`)
+			return 0
+		}
+		rt.log(`\nSyncing packageManager: ${typeof current === "string" ? current : "(missing)"} -> ${expected}`)
+		rt.writeFile(path, withPackageManager(content, path, expected))
+		rt.log(`Updated packageManager to ${expected}`)
+		return 0
+	} catch (error) {
+		rt.error(`Failed to sync packageManager: ${error instanceof Error ? error.message : String(error)}`)
+		return 1
+	}
+}

package/src/config.ts

@@ -0,0 +1,123 @@
+/**
+ * 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)
+ */
+
+import type { BuiltinName } from "./builtins/index.ts"
+import type { BuiltinOverride } from "./builtins/types.ts"
+
+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 }
+
+/**
+ * One shell environment entry, written verbatim into the managed rc block (the shell expands `$HOME`).
+ * - `{ path }` puts a directory first on PATH, so the pinned binary wins over one already installed.
+ * - `{ key, value }` sets a variable.
+ * - `{ key, detect, fallback? }` sets a variable to the first `detect` path that exists, else `fallback`.
+ */
+export type EnvVar =
+	| { path: string }
+	| { key: string; value: string }
+	| { detect: readonly string[]; fallback?: string; key: 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
+		/** Regex source whose first capture is the version. Default: the first `N.N…` in the output. */
+		pattern?: string
+	}
+	/** Deps that must be installed before this one (by dep key name) */
+	dependsOn?: readonly string[]
+	/** Env vars to configure after install */
+	env?: readonly EnvVar[]
+}
+
+/**
+ * One `deps` entry. A built-in name takes its version (`go: "1.27.2"`) or an override object
+ * (`{ version, ...fields to replace, os merged per key }`); any other name is a full custom dep.
+ */
+export type DepEntry<K extends PropertyKey> = K extends BuiltinName ? BuiltinOverride | string : SystemDepConfig
+
+export interface SystemConfig<
+	D extends Record<string, unknown> = Record<string, BuiltinOverride | SystemDepConfig | string>,
+> {
+	deps: { [K in keyof D]: DepEntry<K> }
+	/** package.json whose `packageManager` follows the bun pin. Relative to the config file. */
+	packageJsonPath?: string
+}
+
+/** `{{arch}}` value: "arm64" on arm64, "amd64" everywhere else. */
+export function archLabel(arch: string = process.arch): "amd64" | "arm64" {
+	return arch === "arm64" ? "arm64" : "amd64"
+}
+
+/** Replace {{name}}, {{version}}, {{major}} and {{arch}} in a template. */
+export function interpolate(template: string, name: string, version: string, arch: string = process.arch): string {
+	const major = version.split(".")[0] as string
+	return template
+		.replace(/\{\{name\}\}/g, name)
+		.replace(/\{\{version\}\}/g, version)
+		.replace(/\{\{major\}\}/g, major)
+		.replace(/\{\{arch\}\}/g, archLabel(arch))
+}
+
+/**
+ * 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)
+}
+
+/**
+ * Type a `system.config.ts` default export. Each key is checked on its own: a built-in name takes a
+ * version string or override object, any other name a full `SystemDepConfig`.
+ */
+export function defineConfig<const D extends Record<string, unknown>>(
+	config: SystemConfig<D> & { deps: D },
+): { deps: D; packageJsonPath?: string } {
+	return config
+}

package/src/env.ts

@@ -0,0 +1,103 @@
+/**
+ * Shell rc blocks: which file each shell reads, and the managed block written into it.
+ */
+
+import { basename, resolve } from "node:path"
+
+export type ShellKind = "fish" | "posix" | "powershell"
+
+/** One rendered line: a directory put first on PATH, or a variable set to a value. */
+export type EnvLine = { path: string } | { key: string; value: string }
+
+/** PowerShell on Windows; fish when `SHELL` is fish; posix (bash/zsh) otherwise. */
+export function shellKind(platform: NodeJS.Platform, shell = ""): ShellKind {
+	if (platform === "win32") return "powershell"
+	return basename(shell) === "fish" ? "fish" : "posix"
+}
+
+/**
+ * The rc files the managed block goes into. On Windows both profiles: PowerShell 7 (`pwsh`) reads
+ * `Documents\PowerShell`, Windows PowerShell 5.1 (`powershell.exe`, which `check` snapshots) reads
+ * `Documents\WindowsPowerShell`.
+ */
+export function shellConfigPaths(home: string, kind: ShellKind, shell = "", env: NodeJS.ProcessEnv = {}): string[] {
+	if (kind === "powershell") {
+		return ["PowerShell", "WindowsPowerShell"].map((dir) =>
+			resolve(home, "Documents", dir, "Microsoft.PowerShell_profile.ps1"),
+		)
+	}
+	if (kind === "fish") {
+		return [resolve(env.XDG_CONFIG_HOME ?? resolve(home, ".config"), "fish", "conf.d", "workerstack-system.fish")]
+	}
+	return [resolve(home, shell.includes("zsh") ? ".zshrc" : ".bashrc")]
+}
+
+/**
+ * Expand `$env:VAR`, `$VAR`, `${VAR}` and `%VAR%`. `HOME` and `USERPROFILE` are `home`; every other name comes from
+ * `env`. Names `env` does not define stay literal, so a later shell can still expand them.
+ */
+export function expandPath(path: string, home: string, env: NodeJS.ProcessEnv = process.env): string {
+	const lookup = (name: string): string | undefined => (/^(home|userprofile)$/i.test(name) ? home : env[name])
+	return path.replace(
+		/\$env:(\w+)|\$\{(\w+)\}|\$(\w+)|%(\w+)%/g,
+		(token, ps?: string, braced?: string, bare?: string, percent?: string) =>
+			lookup((ps ?? braced ?? bare ?? percent) as string) ?? token,
+	)
+}
+
+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"), "")
+}
+
+function renderLine(line: EnvLine, kind: ShellKind): string {
+	if ("path" in line) {
+		if (kind === "powershell") return `$env:Path = "${line.path};" + $env:Path`
+		if (kind === "fish") return `set -gx PATH "${line.path}" $PATH`
+		return `export PATH="${line.path}:$PATH"`
+	}
+	if (kind === "powershell") return `$env:${line.key} = "${line.value}"`
+	if (kind === "fish") return `set -gx ${line.key} "${line.value}"`
+	return `export ${line.key}="${line.value}"`
+}
+
+/** The managed block for `tool`. PATH entries go first on PATH so a pinned toolchain wins. */
+export function renderEnvBlock(tool: string, lines: readonly EnvLine[], kind: ShellKind): string {
+	const { end, start } = envMarkers(tool)
+	const nl = kind === "powershell" ? "\r\n" : "\n"
+	return ["", start, ...lines.map((line) => renderLine(line, kind)), end, ""].join(nl)
+}
+
+/** Replace `tool`'s block (current or legacy marker) with `block`; other content is kept. */
+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 reloadHint(kind: ShellKind, configPath: string): string {
+	if (kind === "powershell") return "Restart PowerShell or run: . $PROFILE"
+	if (kind === "fish") return `Run: source ${configPath}   (or restart fish)`
+	return `Run: source ~/${basename(configPath)}   (or restart terminal)`
+}

package/src/errors.ts

@@ -0,0 +1,4 @@
+/** A config the CLI cannot act on. `main` prints the message and exits 1, without a stack. */
+export class ConfigError extends Error {
+	override name = "ConfigError"
+}

package/src/exec.ts

@@ -0,0 +1,64 @@
+import { spawnSync } from "node:child_process"
+
+/** One process spawn: `verbatim` passes args to cmd.exe unquoted, as Node does for `shell: true`. */
+export interface ShellInvocation {
+	args: string[]
+	file: string
+	verbatim: boolean
+}
+
+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,
+	env: NodeJS.ProcessEnv = process.env,
+): ShellInvocation {
+	if (platform !== "win32") return { args: ["-c", command], file: "/bin/bash", verbatim: false }
+	if (needsPowerShell(command)) {
+		return { args: ["-NoProfile", "-NonInteractive", "-Command", command], file: "powershell.exe", verbatim: false }
+	}
+	/* cmd.exe so bun -e / choco / || keep working */
+	return { args: ["/d", "/s", "/c", `"${command}"`], file: env.ComSpec || "cmd.exe", verbatim: true }
+}
+
+/**
+ * The env for spawning `file`. Windows PowerShell 5.1 gets no PSModulePath: one inherited from a pwsh 7
+ * parent points it at 7's modules and breaks autoload (`Get-FileHash` "not recognized"); 5.1 rebuilds
+ * its own default.
+ */
+export function shellEnv(file: string, env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	if (file !== "powershell.exe") return env
+	return Object.fromEntries(Object.entries(env).filter(([key]) => key.toLowerCase() !== "psmodulepath"))
+}
+
+/** Run `command` with inherited stdio. Throws when the shell cannot start or exits non-zero. */
+export function runShellCommand(
+	command: string,
+	platform: NodeJS.Platform = process.platform,
+	env: NodeJS.ProcessEnv = process.env,
+): void {
+	const { args, file, verbatim } = shellInvocation(command, platform, env)
+	const result = spawnSync(file, args, {
+		env: shellEnv(file, env),
+		stdio: "inherit",
+		windowsVerbatimArguments: verbatim,
+	})
+	if (result.error) throw result.error
+	if (result.status !== 0) throw new Error(`exit ${result.status ?? result.signal}: ${command}`)
+}

package/src/graph.ts

@@ -0,0 +1,33 @@
+import type { SystemDepConfig } from "./config.ts"
+import { ConfigError } from "./errors.ts"
+
+/**
+ * Install order: every `dependsOn` target before its dependent, otherwise config order.
+ * Throws `ConfigError` on a `dependsOn` name missing from the config, or on a cycle.
+ */
+export function sortByDependencies<T extends Pick<SystemDepConfig, "dependsOn" | "version">>(
+	entries: Array<[string, T]>,
+): Array<[string, T]> {
+	const byName = new Map(entries)
+	const sorted: Array<[string, T]> = []
+	const done = new Set<string>()
+	const path: string[] = []
+
+	function visit(name: string, config: T): void {
+		if (done.has(name)) return
+		const start = path.indexOf(name)
+		if (start !== -1) throw new ConfigError(`dependency cycle: ${[...path.slice(start), name].join(" → ")}`)
+		path.push(name)
+		for (const dep of config.dependsOn ?? []) {
+			const target = byName.get(dep)
+			if (target === undefined) throw new ConfigError(`deps.${name}.dependsOn: "${dep}" is not a dep in this config`)
+			visit(dep, target)
+		}
+		path.pop()
+		done.add(name)
+		sorted.push([name, config])
+	}
+
+	for (const [name, config] of entries) visit(name, config)
+	return sorted
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @workerstack/system — every OS dependency a workerstack repo needs, from one config.
+ */
+
+export { BUILTIN_GROUPS, BUILTIN_NAMES, BUILTINS, type BuiltinName } from "./builtins/index.ts"
+export { type RawEntry, resolveDeps } from "./builtins/resolve.ts"
+export type { Arch, BuiltinDep, BuiltinOverride, RecipeContext } from "./builtins/types.ts"
+export type { DepEntry, EnvVar, OsCommands, OsTarget, SystemConfig, SystemDepConfig } from "./config.ts"
+export { defineConfig, interpolate, OS_TARGETS, resolveCheckCommand, resolveOsCommand } from "./config.ts"
+export { ConfigError } from "./errors.ts"
+export { sortByDependencies } from "./graph.ts"
+export {
+	commandExists,
+	detectLinuxDistro,
+	detectOs,
+	detectOsFromPlatform,
+	parseOsTarget,
+	whichBinary,
+} from "./platform.ts"
+export { validateConfig } from "./validate.ts"
+export { parseVersion, versionsMatch } from "./version.ts"

package/src/load.ts

@@ -0,0 +1,43 @@
+/**
+ * Config discovery and import. Returns a result, never exits.
+ */
+
+import { resolve } from "node:path"
+import type { SystemConfig } from "./config.ts"
+import type { Runtime } from "./runtime.ts"
+import { validateConfig } from "./validate.ts"
+import { BUILTIN_NAMES } from "./builtins/index.ts"
+
+export const CONFIG_NAMES = ["system.config.ts", "system.config.js", "system.config.mjs"] as const
+
+export type Result<T> = { ok: true; value: T } | { error: string; ok: false }
+
+/** `--config <path>` relative to cwd, else the first convention name in cwd. */
+export function findConfig(rt: Runtime, explicit: string | undefined): Result<string> {
+	if (explicit !== undefined) {
+		const path = resolve(rt.cwd, explicit)
+		return rt.exists(path) ? { ok: true, value: path } : { error: `Config file not found: ${path}`, ok: false }
+	}
+	for (const name of CONFIG_NAMES) {
+		const path = resolve(rt.cwd, name)
+		if (rt.exists(path)) return { ok: true, value: path }
+	}
+	return { error: `No system config found. Create one of: ${CONFIG_NAMES.join(", ")}`, ok: false }
+}
+
+function hasDeps(value: unknown): value is { deps: unknown } {
+	return typeof value === "object" && value !== null && "deps" in value
+}
+
+/**
+ * `export default defineConfig(...)`, else the first named export holding `deps`, validated.
+ * Throws `ConfigError` listing every problem in the config's shape.
+ */
+export async function importConfig(rt: Runtime, path: string): Promise<Result<SystemConfig>> {
+	const mod = await rt.importModule(path)
+	const config = hasDeps(mod.default) ? mod.default : Object.values(mod).find(hasDeps)
+	if (config === undefined) {
+		return { error: "Config file must export an object with a `deps` field (use defineConfig)", ok: false }
+	}
+	return { ok: true, value: validateConfig(config, BUILTIN_NAMES) }
+}

package/src/main.ts

@@ -0,0 +1,99 @@
+/**
+ * The CLI: parse, load the config, dispatch. Returns the exit code; only `bin.ts` exits.
+ */
+
+import { dirname } from "node:path"
+import { parseArgs } from "./args.ts"
+import { BUILTINS } from "./builtins/index.ts"
+import { resolveDeps } from "./builtins/resolve.ts"
+import { checkCommand } from "./commands/check.ts"
+import { envCommand } from "./commands/env.ts"
+import { installCommand } from "./commands/install.ts"
+import { listCommand } from "./commands/list.ts"
+import { syncPmCommand } from "./commands/sync-pm.ts"
+import { ConfigError } from "./errors.ts"
+import { findConfig, importConfig } from "./load.ts"
+import { detectOsFromPlatform } from "./platform.ts"
+import type { Context } from "./probe.ts"
+import type { Runtime } from "./runtime.ts"
+
+export const USAGE = `Usage: system <command> [args]
+
+Commands:
+  install              Install all deps (auto-detect OS)
+  install <name>       Install single dep
+  check                Check all deps
+  check <name>         Check single dep
+  env                  Setup environment variables
+  sync-pm              Sync packageManager field in package.json
+  list                 List built-in deps (give a version: go: "1.27.2")
+
+Flags:
+  --config <path>      Config file (default: system.config.ts in cwd)
+  --os <target>        Force OS target (or set WORKERSTACK_SYSTEM_OS)
+  --dry-run            Print install commands without running them
+  --upgrade            Re-run install when the detected version does not match
+  --here               check: use this process PATH instead of an interactive-shell snapshot
+`
+
+const COMMANDS = ["check", "env", "install", "list", "sync-pm"] as const
+
+async function run(argv: readonly string[], rt: Runtime): Promise<number> {
+	const parsed = parseArgs(argv)
+	if (!parsed.ok) {
+		rt.error(parsed.error)
+		return 1
+	}
+	const args = parsed.value
+
+	if (args.command === undefined || !(COMMANDS as readonly string[]).includes(args.command)) {
+		rt.log(USAGE)
+		if (args.command === undefined) return 0
+		rt.error(`Unknown command: ${args.command}`)
+		return 1
+	}
+
+	if (args.command === "list") return listCommand(rt, BUILTINS)
+
+	const found = findConfig(rt, args.config)
+	if (!found.ok) {
+		rt.error(found.error)
+		return 1
+	}
+	const loaded = await importConfig(rt, found.value)
+	if (!loaded.ok) {
+		rt.error(loaded.error)
+		return 1
+	}
+
+	const override = args.os ?? rt.env.WORKERSTACK_SYSTEM_OS
+	const os = detectOsFromPlatform(rt.platform, override, (command) => rt.which(command) !== null)
+	const ctx: Context = {
+		configDir: dirname(found.value),
+		deps: resolveDeps(loaded.value.deps, { arch: rt.arch, os }, BUILTINS),
+		os,
+		packageJsonPath: loaded.value.packageJsonPath ?? "package.json",
+		rt,
+	}
+
+	switch (args.command) {
+		case "check":
+			return checkCommand(ctx, args.target, args.here)
+		case "env":
+			return envCommand(ctx)
+		case "install":
+			return installCommand(ctx, args.target, { dryRun: args.dryRun, upgrade: args.upgrade })
+		default:
+			return syncPmCommand(ctx)
+	}
+}
+
+export async function main(argv: readonly string[], rt: Runtime): Promise<number> {
+	try {
+		return await run(argv, rt)
+	} catch (error) {
+		if (error instanceof ConfigError) rt.error(error.message)
+		else rt.error(`\nFatal error: ${error instanceof Error ? error.message : String(error)}`)
+		return 1
+	}
+}