systemd-ts 0.0.0

package/README.md

@@ -0,0 +1,4 @@
+# systemd-ts
+
+`systemd-ts` is a library for declaring, rendering, and managing `systemd`
+services and timers from TypeScript.

package/dist/index.d.mts

@@ -0,0 +1,132 @@
+//#region src/index.d.ts
+interface UnitSection {
+  readonly [key: string]: UnitValue | readonly UnitValue[] | undefined;
+}
+interface SystemdServiceOptions {
+  readonly install?: UnitSection;
+  readonly name: string;
+  readonly service: UnitSection;
+  readonly unit?: UnitSection;
+}
+interface SystemdTimerOptions {
+  readonly install?: UnitSection;
+  readonly name: string;
+  readonly timer: UnitSection;
+  readonly unit?: UnitSection;
+}
+interface SystemdOptions {
+  readonly executor?: CommandExecutor;
+  readonly linkUnits?: boolean;
+  readonly scope?: `system` | `user`;
+  readonly unitDir?: string;
+}
+interface CommandResult {
+  readonly stderr: string;
+  readonly stdout: string;
+}
+type CommandExecutor = (command: string, args: readonly string[]) => Promise<CommandResult>;
+interface LogsOptions {
+  readonly lines?: number;
+}
+interface NotifyOptions {
+  readonly executor?: CommandExecutor;
+  readonly pid?: number;
+  readonly socketPath?: string;
+  readonly status?: string;
+}
+interface StartResult {
+  readonly activeState: string;
+  readonly execMainStatus: number | undefined;
+  readonly result: string;
+  readonly subState: string;
+  readonly unit: string;
+}
+interface ExecutableOptions {
+  readonly args?: readonly string[];
+  readonly modulePath?: string;
+  readonly runtimeEntrypoint?: string;
+}
+type StripUnitSuffix<Value extends string, Suffix extends string> = Value extends `${infer Base}${Suffix}` ? Base : Value;
+type ServiceBaseName<Value extends string> = StripUnitSuffix<Value, `.service`>;
+type TimerBaseName<Value extends string> = StripUnitSuffix<Value, `.timer`>;
+type ServiceFilename<Value extends string> = `${ServiceBaseName<Value>}.service`;
+type TimerFilename<Value extends string> = `${TimerBaseName<Value>}.timer`;
+type TimerTargetUnit<TOptions extends SystemdTimerOptions> = TOptions[`timer`] extends {
+  readonly Unit: infer UnitName extends string;
+} ? UnitName : ServiceFilename<TOptions[`name`]>;
+type TimerTargetServiceName<TOptions extends SystemdTimerOptions> = TimerTargetUnit<TOptions> extends `${infer Base}.service` ? Base : never;
+type IsWideString<Value extends string> = string extends Value ? true : false;
+type AnySystemdService = SystemdService<SystemdServiceOptions>;
+type AnySystemdTimer = SystemdTimer<SystemdTimerOptions>;
+type SystemdUnit = AnySystemdService | AnySystemdTimer;
+interface InstalledUnit<TUnit extends SystemdUnit = SystemdUnit> {
+  readonly path: string;
+  readonly unit: TUnit;
+}
+type ServiceNamesIn<TUnits extends readonly SystemdUnit[]> = TUnits[number] extends infer TUnit ? TUnit extends AnySystemdService ? TUnit[`name`] : never : never;
+type TimerMatchesAnyService<TTimer extends AnySystemdTimer, TServiceNames extends string> = IsWideString<TimerTargetServiceName<TTimer[`options`]>> extends true ? true : IsWideString<TServiceNames> extends true ? true : [Extract<TServiceNames, TimerTargetServiceName<TTimer[`options`]>>] extends [never] ? false : true;
+type MismatchedTimers<TUnits extends readonly SystemdUnit[]> = TUnits[number] extends infer TUnit ? TUnit extends AnySystemdTimer ? TimerMatchesAnyService<TUnit, ServiceNamesIn<TUnits>> extends true ? never : TUnit : never : never;
+type HasServices<TUnits extends readonly SystemdUnit[]> = [ServiceNamesIn<TUnits>] extends [never] ? false : true;
+type HasMismatchedServiceTimerPairs<TUnits extends readonly SystemdUnit[]> = HasServices<TUnits> extends true ? [MismatchedTimers<TUnits>] extends [never] ? false : true : false;
+type ValidInstallUnits<TUnits extends readonly SystemdUnit[]> = HasMismatchedServiceTimerPairs<TUnits> extends true ? never : TUnits;
+type UnitValue = string | number | boolean | Executable;
+declare class Executable {
+  readonly args: readonly string[];
+  readonly modulePath: string;
+  readonly runtimeEntrypoint: string;
+  constructor(options?: ExecutableOptions);
+  toCommandParts(): readonly [string, ...string[]];
+  toExecStart(): string;
+}
+declare class SystemdService<const TOptions extends SystemdServiceOptions = SystemdServiceOptions> {
+  readonly install: TOptions[`install`] | undefined;
+  readonly name: ServiceBaseName<TOptions[`name`]>;
+  readonly options: Readonly<TOptions>;
+  readonly service: TOptions[`service`];
+  readonly unit: TOptions[`unit`] | undefined;
+  constructor(options: TOptions);
+  get filename(): ServiceFilename<TOptions[`name`]>;
+  render(): string;
+}
+declare class SystemdTimer<const TOptions extends SystemdTimerOptions = SystemdTimerOptions> {
+  readonly install: TOptions[`install`] | undefined;
+  readonly name: TimerBaseName<TOptions[`name`]>;
+  readonly options: Readonly<TOptions>;
+  readonly targetServiceName: TimerTargetServiceName<TOptions>;
+  readonly targetUnit: TimerTargetUnit<TOptions>;
+  readonly timer: TOptions[`timer`];
+  readonly unit: TOptions[`unit`] | undefined;
+  constructor(options: TOptions);
+  get filename(): TimerFilename<TOptions[`name`]>;
+  render(): string;
+}
+declare class SystemdInstallResult<TUnits extends readonly SystemdUnit[] = readonly SystemdUnit[]> {
+  readonly directory: string;
+  readonly installed: readonly InstalledUnit<TUnits[number]>[];
+  private readonly pathByFilename;
+  constructor(directory: string, installed: readonly InstalledUnit<TUnits[number]>[]);
+  pathFor(unit: TUnits[number]): string;
+}
+declare class Systemd {
+  readonly executor: CommandExecutor;
+  readonly linkUnits: boolean;
+  readonly scope: `system` | `user`;
+  readonly unitDir: string;
+  constructor(options?: SystemdOptions);
+  install<const TUnits extends readonly SystemdUnit[]>(...units: ValidInstallUnits<TUnits>): Promise<SystemdInstallResult<TUnits>>;
+  enable(...units: readonly SystemdUnit[]): Promise<void>;
+  start(unit: SystemdUnit): Promise<StartResult>;
+  logs(_unit: SystemdUnit, _options?: LogsOptions): Promise<string>;
+  pathFor(unit: SystemdUnit): string;
+  private prepareUnits;
+  private scopeArgs;
+  private collectLinkPaths;
+}
+declare function defaultSystemd(): Systemd;
+declare const notify: {
+  ready(options?: NotifyOptions): Promise<void>;
+  watchdog(options?: NotifyOptions): Promise<void>;
+};
+declare function defineExecutable(fn: () => void | Promise<void>, options?: ExecutableOptions): Executable;
+//#endregion
+export { AnySystemdService, AnySystemdTimer, CommandExecutor, CommandResult, Executable, ExecutableOptions, InstalledUnit, LogsOptions, NotifyOptions, StartResult, Systemd, SystemdInstallResult, SystemdOptions, SystemdService, SystemdServiceOptions, SystemdTimer, SystemdTimerOptions, SystemdUnit, UnitSection, UnitValue, defaultSystemd, defineExecutable, notify };

package/dist/index.mjs

@@ -0,0 +1,393 @@
+import { execFile } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+//#region src/index.ts
+const REQUIRED_EXEC_KEYS = [
+	`ExecStart`,
+	`ExecStop`,
+	`ExecReload`
+];
+const execFileAsync = promisify(execFile);
+const currentModulePath = fileURLToPath(import.meta.url);
+var Executable = class {
+	args;
+	modulePath;
+	runtimeEntrypoint;
+	constructor(options = {}) {
+		this.runtimeEntrypoint = options.runtimeEntrypoint ?? process.execPath;
+		this.modulePath = options.modulePath ?? inferCallerModulePath();
+		this.args = Object.freeze([...options.args ?? []]);
+		Object.freeze(this);
+	}
+	toCommandParts() {
+		return [
+			this.runtimeEntrypoint,
+			this.modulePath,
+			...this.args
+		];
+	}
+	toExecStart() {
+		return this.toCommandParts().map(shellQuote).join(` `);
+	}
+};
+var SystemdService = class {
+	install;
+	name;
+	options;
+	service;
+	unit;
+	constructor(options) {
+		this.options = freezeUnitOptions(options);
+		this.name = normalizeUnitName(options.name, `.service`);
+		this.unit = cloneUnitSection(options.unit);
+		this.service = cloneUnitSection(options.service) ?? {};
+		this.install = cloneUnitSection(options.install);
+		Object.freeze(this);
+	}
+	get filename() {
+		return `${this.name}.service`;
+	}
+	render() {
+		validateServiceSection(this.service);
+		return renderUnitFile([
+			[`Unit`, this.unit],
+			[`Service`, this.service],
+			[`Install`, this.install]
+		]);
+	}
+};
+var SystemdTimer = class {
+	install;
+	name;
+	options;
+	targetServiceName;
+	targetUnit;
+	timer;
+	unit;
+	constructor(options) {
+		this.options = freezeUnitOptions(options);
+		this.name = normalizeUnitName(options.name, `.timer`);
+		this.unit = cloneUnitSection(options.unit);
+		this.timer = cloneUnitSection(options.timer) ?? {};
+		this.install = cloneUnitSection(options.install);
+		this.targetUnit = resolveTimerTargetUnit(options);
+		this.targetServiceName = normalizeUnitName(this.targetUnit, `.service`);
+		Object.freeze(this);
+	}
+	get filename() {
+		return `${this.name}.timer`;
+	}
+	render() {
+		return renderUnitFile([
+			[`Unit`, this.unit],
+			[`Timer`, this.timer],
+			[`Install`, this.install]
+		]);
+	}
+};
+var SystemdInstallResult = class {
+	directory;
+	installed;
+	pathByFilename;
+	constructor(directory, installed) {
+		this.directory = directory;
+		this.installed = Object.freeze([...installed]);
+		this.pathByFilename = new Map(installed.map((entry) => [entry.unit.filename, entry.path]));
+		Object.freeze(this);
+	}
+	pathFor(unit) {
+		const path = this.pathByFilename.get(unit.filename);
+		if (path === void 0) throw new Error(`No installed path is recorded for ${unit.filename}`);
+		return path;
+	}
+};
+var Systemd = class {
+	executor;
+	linkUnits;
+	scope;
+	unitDir;
+	constructor(options = {}) {
+		this.scope = options.scope ?? `system`;
+		this.unitDir = options.unitDir ?? defaultUnitDirForScope(this.scope);
+		this.linkUnits = options.linkUnits ?? false;
+		this.executor = options.executor ?? defaultCommandExecutor;
+		Object.freeze(this);
+	}
+	async install(...units) {
+		if (units.length === 0) throw new Error(`Systemd.install() requires at least one service or timer`);
+		assertInstallableTogether(units);
+		await mkdir(this.unitDir, { recursive: true });
+		const installed = [];
+		for (const unit of units) {
+			const path = join(this.unitDir, unit.filename);
+			await writeFile(path, unit.render(), `utf8`);
+			installed.push({
+				path,
+				unit
+			});
+		}
+		return new SystemdInstallResult(this.unitDir, installed);
+	}
+	async enable(...units) {
+		if (units.length === 0) throw new Error(`Systemd.enable() requires at least one service or timer`);
+		const scopeArgs = this.scopeArgs();
+		await this.prepareUnits(scopeArgs, units);
+		for (const unit of units) await this.executor(`systemctl`, [
+			...scopeArgs,
+			`enable`,
+			unit.filename
+		]);
+	}
+	async start(unit) {
+		const scopeArgs = this.scopeArgs();
+		await this.prepareUnits(scopeArgs, [unit]);
+		await this.executor(`systemctl`, [
+			...scopeArgs,
+			`start`,
+			unit.filename
+		]);
+		const status = await this.executor(`systemctl`, [
+			...scopeArgs,
+			`show`,
+			unit.filename,
+			`--property=Id,ActiveState,SubState,Result,ExecMainStatus`
+		]);
+		return parseStartResult(unit.filename, status.stdout);
+	}
+	async logs(_unit, _options) {
+		const fileLogPath = resolveUnitLogPath(_unit);
+		if (fileLogPath !== void 0) return tailLines(await readFile(fileLogPath, `utf8`), _options?.lines ?? 50);
+		const scopeArgs = this.scopeArgs();
+		const lines = _options?.lines ?? 50;
+		const command = [
+			`systemctl`,
+			...scopeArgs,
+			`status`,
+			_unit.filename,
+			`--no-pager`,
+			`--lines`,
+			String(lines)
+		].map(shellQuote).join(` `);
+		return (await this.executor(`bash`, [`-lc`, `${command} || true`])).stdout;
+	}
+	pathFor(unit) {
+		return join(this.unitDir, unit.filename);
+	}
+	async prepareUnits(scopeArgs, units) {
+		if (this.linkUnits) {
+			const linkPaths = await this.collectLinkPaths(units);
+			for (const path of linkPaths) await this.executor(`systemctl`, [
+				...scopeArgs,
+				`link`,
+				path
+			]);
+		}
+		await this.executor(`systemctl`, [...scopeArgs, `daemon-reload`]);
+	}
+	scopeArgs() {
+		return this.scope === `user` ? [`--user`] : [];
+	}
+	async collectLinkPaths(units) {
+		const paths = /* @__PURE__ */ new Set();
+		for (const unit of units) {
+			paths.add(this.pathFor(unit));
+			if (unit instanceof SystemdTimer) {
+				const targetPath = join(this.unitDir, unit.targetUnit);
+				if (await fileExists(targetPath)) paths.add(targetPath);
+			}
+		}
+		return [...paths];
+	}
+};
+function resolveUnitLogPath(unit) {
+	if (!(unit instanceof SystemdService)) return;
+	for (const key of [`StandardOutput`, `StandardError`]) {
+		const value = unit.service[key];
+		if (typeof value !== `string`) continue;
+		const path = parseFileLogPath(value);
+		if (path !== void 0) return path;
+	}
+}
+function parseFileLogPath(value) {
+	for (const prefix of [`append:`, `file:`]) if (value.startsWith(prefix)) return value.slice(prefix.length);
+}
+function tailLines(output, lines) {
+	return output.split(`\n`).slice(-lines).join(`\n`);
+}
+let lazyDefaultSystemd;
+function defaultSystemd() {
+	lazyDefaultSystemd ??= new Systemd();
+	return lazyDefaultSystemd;
+}
+const notify = {
+	async ready(options = {}) {
+		await sendNotify(`READY=1`, options);
+	},
+	async watchdog(options = {}) {
+		await sendNotify(`WATCHDOG=1`, options);
+	}
+};
+function defineExecutable(fn, options = {}) {
+	const executable = new Executable(options);
+	if (isMainModule(executable.modulePath)) Promise.resolve(fn()).catch((error) => {
+		process.exitCode = 1;
+		throw error;
+	});
+	return executable;
+}
+function normalizeUnitName(name, suffix) {
+	return name.endsWith(suffix) ? name.slice(0, -suffix.length) : name;
+}
+function resolveTimerTargetUnit(options) {
+	const explicitTarget = options.timer[`Unit`];
+	if (typeof explicitTarget === `string` && explicitTarget.length > 0) return explicitTarget;
+	return `${normalizeUnitName(options.name, `.timer`)}.service`;
+}
+function defaultUnitDirForScope(scope) {
+	if (scope === `user`) return `${process.env[`HOME`] ?? `~`}/.config/systemd/user`;
+	return `/etc/systemd/system`;
+}
+function freezeUnitOptions(options) {
+	return Object.freeze({
+		...options,
+		...options.unit === void 0 ? {} : { unit: cloneUnitSection(options.unit) },
+		...options.install === void 0 ? {} : { install: cloneUnitSection(options.install) },
+		...hasServiceSection(options) ? { service: cloneUnitSection(options.service) } : {},
+		...hasTimerSection(options) ? { timer: cloneUnitSection(options.timer) } : {}
+	});
+}
+function hasServiceSection(options) {
+	return `service` in options;
+}
+function hasTimerSection(options) {
+	return `timer` in options;
+}
+function cloneUnitSection(section) {
+	if (section === void 0) return section;
+	const entries = Object.entries(section).map(([key, value]) => {
+		if (isUnitValueList(value)) return [key, Object.freeze([...value])];
+		return [key, value];
+	});
+	return Object.freeze(Object.fromEntries(entries));
+}
+function validateServiceSection(service) {
+	for (const key of REQUIRED_EXEC_KEYS) {
+		const value = service[key];
+		if (typeof value === `string` && value.length > 0 && !value.startsWith(`/`)) throw new Error(`${key} must use an absolute executable path for systemd`);
+		if (value instanceof Executable && !value.runtimeEntrypoint.startsWith(`/`)) throw new Error(`${key} must use an absolute executable path for systemd`);
+	}
+}
+function assertInstallableTogether(units) {
+	const installedServices = new Set(units.filter((unit) => unit instanceof SystemdService).map((unit) => unit.name));
+	if (installedServices.size === 0) return;
+	for (const unit of units) {
+		if (!(unit instanceof SystemdTimer)) continue;
+		if (!installedServices.has(unit.targetServiceName)) throw new Error(`Cannot install ${unit.filename} alongside unrelated services: expected ${unit.targetUnit}`);
+	}
+}
+function parseStartResult(unit, output) {
+	const properties = Object.fromEntries(output.split(`\n`).map((line) => line.trim()).filter((line) => line.length > 0).map((line) => {
+		const separatorIndex = line.indexOf(`=`);
+		if (separatorIndex === -1) return [line, ``];
+		return [line.slice(0, separatorIndex), line.slice(separatorIndex + 1)];
+	}));
+	return {
+		activeState: properties[`ActiveState`] ?? `unknown`,
+		execMainStatus: properties[`ExecMainStatus`] === void 0 || properties[`ExecMainStatus`] === `` ? void 0 : Number(properties[`ExecMainStatus`]),
+		result: properties[`Result`] ?? `unknown`,
+		subState: properties[`SubState`] ?? `unknown`,
+		unit: properties[`Id`] ?? unit
+	};
+}
+function renderUnitFile(sections) {
+	const renderedSections = sections.flatMap(([sectionName, section]) => {
+		if (section === void 0) return [];
+		const lines = Object.entries(section).flatMap(([key, value]) => {
+			if (value === void 0) return [];
+			if (isUnitValueList(value)) return value.map((entry) => `${key}=${stringifyUnitValue(entry)}`);
+			return `${key}=${stringifyUnitValue(value)}`;
+		});
+		if (lines.length === 0) return [];
+		return [
+			`[${sectionName}]`,
+			...lines,
+			``
+		];
+	}).join(`\n`);
+	return renderedSections.endsWith(`\n`) ? renderedSections : `${renderedSections}\n`;
+}
+function stringifyUnitValue(value) {
+	if (value instanceof Executable) return value.toExecStart();
+	if (typeof value === `boolean`) return value ? `true` : `false`;
+	return String(value);
+}
+function isUnitValueList(value) {
+	return Array.isArray(value);
+}
+function inferCallerModulePath() {
+	const stack = (/* @__PURE__ */ new Error()).stack ?? ``;
+	for (const line of stack.split(`\n`).slice(1)) {
+		const candidate = extractStackPath(line);
+		if (candidate === void 0 || candidate === currentModulePath) continue;
+		return candidate;
+	}
+	throw new Error(`Could not infer the calling module path for defineExecutable(); pass { modulePath } explicitly`);
+}
+function extractStackPath(line) {
+	const fileUrlMatch = line.match(/(file:\/\/\/[^)\s:]+(?:\.[cm]?[jt]s)?)/u);
+	if (fileUrlMatch !== null) return fileURLToPath(fileUrlMatch[1]);
+	const pathMatch = line.match(/(\/[^)\s:]+(?:\.[cm]?[jt]s)?)/u);
+	if (pathMatch !== null) return pathMatch[1];
+}
+function isMainModule(modulePath) {
+	const mainArg = process.argv[1];
+	if (mainArg === void 0) return false;
+	return normalizeFilePath(mainArg) === normalizeFilePath(modulePath);
+}
+function shellQuote(value) {
+	return `'${value.replaceAll(`'`, `'\\''`)}'`;
+}
+function normalizeFilePath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+async function defaultCommandExecutor(command, args) {
+	const result = await execFileAsync(command, [...args]);
+	return {
+		stderr: result.stderr,
+		stdout: result.stdout
+	};
+}
+async function fileExists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function sendNotify(state, options) {
+	const args = [state];
+	if (options.pid !== void 0) args.push(`MAINPID=${options.pid}`);
+	if (options.status !== void 0) args.push(`STATUS=${options.status}`);
+	if (options.executor !== void 0) {
+		const command = buildNotifyShellCommand(args, options.socketPath);
+		await options.executor(`bash`, [`-lc`, command]);
+		return;
+	}
+	await execFileAsync(`systemd-notify`, args, { env: {
+		...process.env,
+		...options.socketPath === void 0 ? {} : { NOTIFY_SOCKET: options.socketPath }
+	} });
+}
+function buildNotifyShellCommand(args, socketPath) {
+	return `${socketPath === void 0 ? `` : `NOTIFY_SOCKET=${shellQuote(socketPath)} `}${[`systemd-notify`, ...args].map(shellQuote).join(` `)}`;
+}
+//#endregion
+export { Executable, Systemd, SystemdInstallResult, SystemdService, SystemdTimer, defaultSystemd, defineExecutable, notify };

package/dist/test.d.mts

@@ -0,0 +1,28 @@
+//#region src/testing/host.d.ts
+interface TestHostInfo {
+  readonly backend: TestHostBackendName;
+  readonly colimaHome?: string;
+  readonly colimaProfile?: string;
+  readonly limaHome?: string;
+  readonly repoRoot: string;
+  readonly stateRoot: string;
+}
+type TestHostBackendName = `colima` | `docker`;
+declare function getTestHostInfo(): TestHostInfo;
+declare function ensureTestHost(): Promise<TestHostInfo>;
+declare function closeTestHost(): void;
+declare function runGuestCommand(script: string): Promise<string>;
+//#endregion
+//#region src/testing/sandbox.d.ts
+interface TestSandbox {
+  readonly id: string;
+  readonly linkedUnitDir: string;
+  readonly namePrefix: string;
+  readonly rootDir: string;
+  readonly workDir: string;
+}
+declare function createTestSandbox(testName?: string): Promise<TestSandbox>;
+declare function destroyCurrentTestSandbox(): Promise<void>;
+declare function useCurrentTestSandbox(): TestSandbox;
+//#endregion
+export { type TestHostInfo, type TestSandbox, closeTestHost, createTestSandbox, destroyCurrentTestSandbox, ensureTestHost, getTestHostInfo, runGuestCommand, useCurrentTestSandbox };

package/dist/test.mjs

@@ -0,0 +1,508 @@
+import { execFile, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { createHash, randomUUID } from "node:crypto";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+//#region src/testing/host.ts
+const execFileAsync = promisify(execFile);
+const commandMaxBufferBytes = 16 * 1024 * 1024;
+const dockerBuildTimeoutMs = 300 * 1e3;
+const dockerExecTimeoutMs = 60 * 1e3;
+const guestCommandTimeoutMs = 10 * 1e3;
+const repoRoot = fileURLToPath(new URL(`../../../../`, import.meta.url));
+const dockerfilePath = fileURLToPath(new URL(`./systemd-container.Dockerfile`, import.meta.url));
+const selectedBackendName = resolveBackendName(process.env[`SYSTEMD_TS_TEST_HOST_BACKEND`]);
+const colimaHome = process.env[`COLIMA_HOME`] ?? `${repoRoot}.colima`;
+const limaHome = process.env[`LIMA_HOME`] ?? `${colimaHome}/_lima`;
+const colimaProfile = process.env[`COLIMA_PROFILE`] ?? `systemd-ts`;
+const dockerStateRoot = process.env[`SYSTEMD_TS_TEST_HOST_ROOT`] ?? `${repoRoot}.docker`;
+const dockerImage = process.env[`SYSTEMD_TS_TEST_DOCKER_IMAGE`] ?? `systemd-ts-test-host:local`;
+const dockerUser = process.env[`SYSTEMD_TS_TEST_DOCKER_USER`] ?? `runner`;
+const dockerConfiguredUserId = process.env[`SYSTEMD_TS_TEST_DOCKER_UID`];
+const dockerContainer = process.env[`SYSTEMD_TS_TEST_DOCKER_CONTAINER`] ?? defaultDockerContainerName();
+let ensuredHost;
+let guestShell;
+function getTestHostInfo() {
+	return backend.info;
+}
+function ensureTestHost() {
+	ensuredHost ??= ensureTestHostInner();
+	return ensuredHost;
+}
+function closeTestHost() {
+	closeGuestShell(`warmup complete`);
+}
+async function runGuestCommand(script) {
+	return getGuestShell().run(script);
+}
+async function ensureTestHostInner() {
+	logTestHost(`Ensuring ${backend.info.backend} test host`);
+	await backend.ensureHost();
+	logTestHost(`Waiting for systemd --user readiness`);
+	await waitForUserSystemd();
+	logTestHost(`Test host ready`);
+	return getTestHostInfo();
+}
+async function waitForUserSystemd() {
+	for (let attempt = 0; attempt < 30; attempt += 1) {
+		const state = await runGuestCommandWithTimeout(`printf 'pid1=%s\n' "$(ps -p 1 -o comm=)"; systemctl --user is-system-running || true; printf 'xdg=%s\n' "$XDG_RUNTIME_DIR"`, guestCommandTimeoutMs);
+		if (state.includes(`pid1=systemd`) && state.includes(`xdg=/run/user/`) && [`running`, `degraded`].some((status) => state.includes(status))) {
+			logTestHost(`systemd --user ready after ${attempt + 1} attempt${attempt === 0 ? `` : `s`}: ${summarizeSystemdState(state)}`);
+			return;
+		}
+		if (attempt === 0 || (attempt + 1) % 5 === 0) logTestHost(`systemd --user not ready yet (${attempt + 1}/30): ${summarizeSystemdState(state)}`);
+		await setTimeout$1(1e3);
+	}
+	throw new Error(`Timed out waiting for systemd --user in the ${backend.info.backend} guest`);
+}
+function getGuestShell() {
+	guestShell ??= new GuestShell(() => backend.createGuestShellProcess(), () => {
+		if (guestShell !== void 0) guestShell = void 0;
+	});
+	return guestShell;
+}
+function closeGuestShell(reason) {
+	if (guestShell === void 0) return;
+	logTestHost(`Resetting guest shell: ${reason}`);
+	guestShell.close();
+	guestShell = void 0;
+}
+async function runGuestCommandWithTimeout(script, timeoutMs) {
+	const shell = getGuestShell();
+	try {
+		return await shell.run(script, timeoutMs);
+	} catch (error) {
+		if (error instanceof Error && error.message.includes(`timed out`)) closeGuestShell(error.message);
+		throw error;
+	}
+}
+function mergeOutput(stdout, stderr) {
+	return [stdout, stderr].filter((output) => output.length > 0).join(`\n`);
+}
+function summarizeSystemdState(state) {
+	return state.split(`\n`).map((line) => line.trim()).filter((line) => line.length > 0).join(`; `);
+}
+function inferBackendName() {
+	if (process.platform === `darwin`) return `colima`;
+	if (process.platform === `linux`) return `docker`;
+	throw new Error(`Unsupported test host platform: ${process.platform}. Set SYSTEMD_TS_TEST_HOST_BACKEND explicitly if you have a compatible backend.`);
+}
+function resolveBackendName(value) {
+	if (value === void 0) return inferBackendName();
+	if (value === `colima` || value === `docker`) return value;
+	throw new Error(`Unsupported SYSTEMD_TS_TEST_HOST_BACKEND value: ${value}. Expected "colima" or "docker".`);
+}
+function defaultDockerContainerName() {
+	return `systemd-ts-${createHash(`sha256`).update(repoRoot).digest(`hex`).slice(0, 12)}`;
+}
+function logTestHost(message) {
+	console.info(`[systemd-ts:test-host] ${message}`);
+}
+function createBackend(name) {
+	switch (name) {
+		case `colima`: return new ColimaBackend();
+		case `docker`: return new DockerBackend();
+	}
+}
+var ColimaBackend = class {
+	info = {
+		backend: `colima`,
+		colimaHome,
+		colimaProfile,
+		limaHome,
+		repoRoot,
+		stateRoot: colimaHome
+	};
+	async ensureHost() {
+		if (await this.isRunning()) return;
+		console.info(`Starting repo-local Colima host for integration tests...`);
+		await this.execColima([
+			`start`,
+			`--cpu`,
+			`2`,
+			`--memory`,
+			`4`,
+			`--disk`,
+			`30`,
+			`--runtime`,
+			`containerd`
+		]);
+	}
+	createGuestShellProcess() {
+		return spawn(`colima`, [
+			`ssh`,
+			`--`,
+			`bash`,
+			`--noprofile`,
+			`--norc`,
+			`-s`
+		], {
+			env: this.hostEnv,
+			stdio: [
+				`pipe`,
+				`pipe`,
+				`pipe`
+			]
+		});
+	}
+	async runIsolatedCommand(script) {
+		return this.execColima([
+			`ssh`,
+			`--`,
+			`bash`,
+			`-lc`,
+			script
+		]);
+	}
+	hostEnv = {
+		...process.env,
+		COLIMA_HOME: colimaHome,
+		COLIMA_PROFILE: colimaProfile,
+		LIMA_HOME: limaHome
+	};
+	async isRunning() {
+		try {
+			return (await this.execColima([`status`])).includes(`is running`);
+		} catch {
+			return false;
+		}
+	}
+	async execColima(args) {
+		const result = await execFileAsync(`colima`, args, {
+			env: this.hostEnv,
+			maxBuffer: commandMaxBufferBytes
+		});
+		return mergeOutput(result.stdout, result.stderr);
+	}
+};
+var DockerBackend = class {
+	info = {
+		backend: `docker`,
+		repoRoot,
+		stateRoot: dockerStateRoot
+	};
+	runtimeInfo;
+	async ensureHost() {
+		logTestHost(`Building Docker test host image ${dockerImage}`);
+		await this.execDocker([
+			`build`,
+			`--quiet`,
+			`--tag`,
+			dockerImage,
+			`--file`,
+			dockerfilePath,
+			repoRoot
+		], { timeout: dockerBuildTimeoutMs });
+		logTestHost(`Docker test host image ready`);
+		if (!await this.isContainerRunning()) {
+			await this.removeExistingContainer();
+			logTestHost(`Starting Docker test host container ${dockerContainer}`);
+			await this.execDocker([
+				`run`,
+				`--detach`,
+				`--name`,
+				dockerContainer,
+				`--hostname`,
+				`systemd-ts-test-host`,
+				`--privileged`,
+				`--cgroupns=host`,
+				`--tmpfs`,
+				`/run`,
+				`--tmpfs`,
+				`/run/lock`,
+				`--volume`,
+				`/sys/fs/cgroup:/sys/fs/cgroup:rw`,
+				`--volume`,
+				`${repoRoot}:${repoRoot}`,
+				`--volume`,
+				`${dockerStateRoot}:${dockerStateRoot}`,
+				`--workdir`,
+				repoRoot,
+				dockerImage
+			]);
+			logTestHost(`Docker test host container started`);
+		} else logTestHost(`Reusing running Docker test host container ${dockerContainer}`);
+		await this.ensureUserSession();
+	}
+	createGuestShellProcess() {
+		const runtimeInfo = this.requireRuntimeInfo();
+		return spawn(`docker`, [
+			`exec`,
+			`--interactive`,
+			`--user`,
+			dockerUser,
+			`--env`,
+			`HOME=${runtimeInfo.home}`,
+			`--env`,
+			`XDG_RUNTIME_DIR=${runtimeInfo.runtimeDir}`,
+			`--env`,
+			`DBUS_SESSION_BUS_ADDRESS=unix:path=${runtimeInfo.runtimeDir}/bus`,
+			dockerContainer,
+			`bash`,
+			`--noprofile`,
+			`--norc`,
+			`-s`
+		], { stdio: [
+			`pipe`,
+			`pipe`,
+			`pipe`
+		] });
+	}
+	async runIsolatedCommand(script) {
+		const runtimeInfo = this.requireRuntimeInfo();
+		const result = await this.execDockerAsUser(runtimeInfo, [
+			`bash`,
+			`-lc`,
+			script
+		]);
+		return mergeOutput(result.stdout, result.stderr);
+	}
+	async isContainerRunning() {
+		try {
+			return (await this.execDocker([
+				`inspect`,
+				`--format`,
+				`{{.State.Running}}`,
+				dockerContainer
+			])).trim() === `true`;
+		} catch {
+			return false;
+		}
+	}
+	async removeExistingContainer() {
+		try {
+			await this.execDocker([
+				`rm`,
+				`--force`,
+				dockerContainer
+			]);
+		} catch {}
+	}
+	async ensureUserSession() {
+		const runtimeInfo = await this.resolveRuntimeInfo();
+		logTestHost(`Ensuring user session for ${dockerUser} (uid=${runtimeInfo.userId}, home=${runtimeInfo.home})`);
+		await this.execDocker([
+			`exec`,
+			dockerContainer,
+			`bash`,
+			`-lc`,
+			[
+				`mkdir -p ${shellQuote$1(dockerStateRoot)}`,
+				`chown ${runtimeInfo.userId}:${runtimeInfo.userId} ${shellQuote$1(dockerStateRoot)}`,
+				`loginctl enable-linger ${shellQuote$1(dockerUser)}`,
+				`systemctl start user@${runtimeInfo.userId}.service`
+			].join(`\n`)
+		], { timeout: dockerExecTimeoutMs });
+		await this.execDockerAsUser(runtimeInfo, [
+			`bash`,
+			`-lc`,
+			`mkdir -p ${shellQuote$1(`${dockerStateRoot}/tests`)}`
+		]);
+		logTestHost(`User session started for ${dockerUser}`);
+	}
+	async execDocker(args, options) {
+		const result = await execFileAsync(`docker`, args, {
+			maxBuffer: commandMaxBufferBytes,
+			timeout: options?.timeout
+		});
+		return mergeOutput(result.stdout, result.stderr);
+	}
+	execDockerAsUser(runtimeInfo, command) {
+		return execFileAsync(`docker`, [
+			`exec`,
+			`--user`,
+			dockerUser,
+			`--env`,
+			`HOME=${runtimeInfo.home}`,
+			`--env`,
+			`XDG_RUNTIME_DIR=${runtimeInfo.runtimeDir}`,
+			`--env`,
+			`DBUS_SESSION_BUS_ADDRESS=unix:path=${runtimeInfo.runtimeDir}/bus`,
+			dockerContainer,
+			...command
+		], { maxBuffer: commandMaxBufferBytes });
+	}
+	requireRuntimeInfo() {
+		if (this.runtimeInfo === void 0) throw new Error(`Docker test host runtime info is unavailable before ensureHost() completes`);
+		return this.runtimeInfo;
+	}
+	async resolveRuntimeInfo() {
+		if (this.runtimeInfo !== void 0) return this.runtimeInfo;
+		const userId = dockerConfiguredUserId === void 0 ? await this.lookupUserId() : Number(dockerConfiguredUserId);
+		const home = await this.lookupUserHome();
+		this.runtimeInfo = {
+			home,
+			runtimeDir: `/run/user/${userId}`,
+			userId
+		};
+		return this.runtimeInfo;
+	}
+	async lookupUserHome() {
+		logTestHost(`Resolving home directory for Docker test user ${dockerUser}`);
+		const home = (await this.execDocker([
+			`exec`,
+			dockerContainer,
+			`bash`,
+			`-lc`,
+			`getent passwd ${shellQuote$1(dockerUser)} | cut -d: -f6`
+		])).trim();
+		if (home.length === 0) throw new Error(`Could not resolve home directory for Docker test user ${dockerUser}`);
+		logTestHost(`Resolved home directory for ${dockerUser}: ${home}`);
+		return home;
+	}
+	async lookupUserId() {
+		logTestHost(`Resolving uid for Docker test user ${dockerUser}`);
+		const output = await this.execDocker([
+			`exec`,
+			dockerContainer,
+			`bash`,
+			`-lc`,
+			`id -u ${shellQuote$1(dockerUser)}`
+		]);
+		const parsed = Number(output.trim());
+		if (!Number.isInteger(parsed)) throw new Error(`Could not resolve uid for Docker test user ${dockerUser}`);
+		logTestHost(`Resolved uid for ${dockerUser}: ${parsed}`);
+		return parsed;
+	}
+};
+var GuestShell = class {
+	process;
+	onExitCleanup;
+	closed = false;
+	buffer = ``;
+	current;
+	queue = [];
+	constructor(createProcess, onExitCleanup) {
+		this.process = createProcess();
+		this.onExitCleanup = onExitCleanup;
+		this.process.stdout.setEncoding(`utf8`);
+		this.process.stderr.setEncoding(`utf8`);
+		this.process.stdout.on(`data`, (chunk) => this.onData(chunk));
+		this.process.stderr.on(`data`, (chunk) => this.onData(chunk));
+		this.process.on(`exit`, (code, signal) => {
+			const reason = /* @__PURE__ */ new Error(`Persistent guest shell exited unexpectedly (code=${code ?? `null`}, signal=${signal ?? `null`})`);
+			this.failCurrent(reason);
+			while (this.queue.length > 0) this.queue.shift()?.reject(reason);
+			this.onExitCleanup();
+		});
+		process.once(`exit`, () => {
+			this.process.kill();
+		});
+	}
+	run(script, timeoutMs) {
+		return new Promise((resolve, reject) => {
+			this.queue.push({
+				script,
+				resolve,
+				reject,
+				timeoutMs
+			});
+			this.drain();
+		});
+	}
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.process.kill();
+	}
+	drain() {
+		if (this.current !== void 0) return;
+		const next = this.queue.shift();
+		if (next === void 0) return;
+		const marker = `__SYSTEMD_TS_END_${randomUUID()}__`;
+		const timeoutId = next.timeoutMs === void 0 ? void 0 : setTimeout(() => {
+			if (this.current?.marker !== marker) return;
+			const reason = /* @__PURE__ */ new Error(`Guest command timed out after ${next.timeoutMs}ms`);
+			this.failCurrent(reason);
+			this.close();
+		}, next.timeoutMs);
+		this.current = {
+			marker,
+			timeoutId,
+			reject: next.reject,
+			resolve: next.resolve
+		};
+		this.buffer = ``;
+		const command = `(
+${next.script}
+) 2>&1
+status=$?
+printf '\\n${marker}:%s\\n' "$status"
+`;
+		this.process.stdin.write(command);
+	}
+	failCurrent(error) {
+		const current = this.current;
+		this.current = void 0;
+		if (current?.timeoutId !== void 0) clearTimeout(current.timeoutId);
+		current?.reject(error);
+	}
+	onData(chunk) {
+		if (this.current === void 0) return;
+		this.buffer += chunk;
+		const markerIndex = this.buffer.indexOf(this.current.marker);
+		if (markerIndex === -1) return;
+		const output = this.buffer.slice(0, markerIndex).replace(/\n$/, ``);
+		const statusMatch = this.buffer.slice(markerIndex).match(/^__SYSTEMD_TS_END_[^:]+__:(\d+)\r?\n?/u);
+		if (statusMatch === null) return;
+		const status = Number(statusMatch[1]);
+		const remainder = this.buffer.slice(markerIndex + statusMatch[0].length);
+		const current = this.current;
+		this.current = void 0;
+		this.buffer = remainder;
+		if (current.timeoutId !== void 0) clearTimeout(current.timeoutId);
+		if (status === 0) current.resolve(output);
+		else current.reject(new Error(output.length > 0 ? output : `Guest command failed`));
+		this.drain();
+	}
+};
+function shellQuote$1(value) {
+	return `'${value.replaceAll(`'`, `'\\''`)}'`;
+}
+const backend = createBackend(selectedBackendName);
+//#endregion
+//#region src/testing/sandbox.ts
+let currentSandbox;
+async function createTestSandbox(testName) {
+	const id = randomUUID().slice(0, 8);
+	const namePrefix = `systemd-ts-${slugify(testName ?? `sandbox`)}-${id}`;
+	const rootDir = `${getTestHostInfo().stateRoot}/tests/${namePrefix}`;
+	const linkedUnitDir = `${rootDir}/linked-units`;
+	const workDir = `${rootDir}/work`;
+	await runGuestCommand(`set -euo pipefail
+rm -rf ${shellQuote(rootDir)}
+mkdir -p ${shellQuote(linkedUnitDir)} ${shellQuote(workDir)}`);
+	currentSandbox = {
+		id,
+		linkedUnitDir,
+		namePrefix,
+		rootDir,
+		workDir
+	};
+	return currentSandbox;
+}
+async function destroyCurrentTestSandbox() {
+	if (currentSandbox === void 0) return;
+	const sandbox = currentSandbox;
+	currentSandbox = void 0;
+	const units = (await runGuestCommand(`systemctl --user list-unit-files --all --no-legend ${shellQuote(`${sandbox.namePrefix}*`)} 2>/dev/null | awk '{print $1}' || true`)).split(`\n`).map((unit) => unit.trim()).filter((unit) => unit.length > 0);
+	if (units.length > 0) {
+		await runGuestCommand(`systemctl --user stop ${units.map(shellQuote).join(` `)} || true`);
+		await runGuestCommand(`systemctl --user disable ${units.map(shellQuote).join(` `)} || true`);
+		await runGuestCommand(`systemctl --user reset-failed ${units.map(shellQuote).join(` `)} || true`);
+	}
+	await runGuestCommand(`systemctl --user daemon-reload || true`);
+	await runGuestCommand(`rm -rf ${shellQuote(sandbox.rootDir)}`);
+}
+function useCurrentTestSandbox() {
+	if (currentSandbox === void 0) throw new Error(`No active test sandbox is available`);
+	return currentSandbox;
+}
+function shellQuote(value) {
+	return `'${value.replaceAll(`'`, `'\\''`)}'`;
+}
+function slugify(value) {
+	return value.toLowerCase().replaceAll(/[^a-z0-9]+/g, `-`).replaceAll(/^-+|-+$/g, ``).slice(0, 32);
+}
+//#endregion
+export { closeTestHost, createTestSandbox, destroyCurrentTestSandbox, ensureTestHost, getTestHostInfo, runGuestCommand, useCurrentTestSandbox };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "systemd-ts",
+  "version": "0.0.0",
+  "description": "TypeScript builders and helpers for systemd services and timers.",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./test": "./dist/test.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@typescript/native-preview": "catalog:",
+    "takua": "catalog:",
+    "typescript": "catalog:",
+    "vite-plus": "catalog:"
+  }
+}