systemd-ts 0.3.0 → 0.3.2

package/dist/main-BXq7TQdg.mjs

@@ -0,0 +1,1612 @@
+import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { join } from "node:path";
+//#region src/main/errors.ts
+var SystemdTsError = class extends Error {
+	code;
+	constructor(code, message, options = {}) {
+		super(message, { cause: options.cause });
+		this.code = code;
+		this.name = new.target.name;
+	}
+};
+var InvalidExecDirectiveError = class extends SystemdTsError {
+	directive;
+	constructor(directive, options = {}) {
+		super(`SYSTEMD_TS_INVALID_EXEC_DIRECTIVE`, `${directive} must use an absolute executable path for systemd`, options);
+		this.directive = directive;
+	}
+};
+var NoUnitsProvidedError = class extends SystemdTsError {
+	operation;
+	constructor(operation, options = {}) {
+		super(`SYSTEMD_TS_NO_UNITS_PROVIDED`, `${operation} requires at least one service or timer`, options);
+		this.operation = operation;
+	}
+};
+var ExecutableInferenceError = class extends SystemdTsError {
+	constructor(options = {}) {
+		super(`SYSTEMD_TS_EXECUTABLE_INFERENCE`, `Could not infer the calling module path for defineExecutable(); pass { modulePath } explicitly`, options);
+	}
+};
+var UnitMaterializationError = class extends SystemdTsError {
+	operation;
+	reason;
+	unitName;
+	unitPath;
+	constructor(message, options = {}) {
+		super(`SYSTEMD_TS_UNIT_MATERIALIZATION`, message, options);
+		this.operation = options.operation;
+		this.reason = options.reason;
+		this.unitName = options.unitName;
+		this.unitPath = options.unitPath;
+	}
+};
+var UnitEnableError = class extends SystemdTsError {
+	args;
+	command;
+	environmentReason;
+	exitCode;
+	stage;
+	stderr;
+	stdout;
+	unitName;
+	unitPath;
+	constructor(message, options = {}) {
+		super(`SYSTEMD_TS_UNIT_ENABLE`, message, options);
+		const details = extractCommandErrorDetails(options.cause);
+		this.args = options.args;
+		this.command = options.command;
+		this.environmentReason = options.environmentReason ?? classifyCommandEnvironmentReason(options.cause);
+		this.exitCode = details.exitCode;
+		this.stage = options.stage;
+		this.stderr = details.stderr;
+		this.stdout = details.stdout;
+		this.unitName = options.unitName;
+		this.unitPath = options.unitPath;
+	}
+};
+var UnitStartError = class extends SystemdTsError {
+	args;
+	command;
+	diagnostics;
+	environmentReason;
+	exitCode;
+	stage;
+	stderr;
+	stdout;
+	unitName;
+	unitPath;
+	constructor(message, options = {}) {
+		super(`SYSTEMD_TS_UNIT_START`, message, options);
+		const details = extractCommandErrorDetails(options.cause);
+		this.args = options.args;
+		this.command = options.command;
+		this.diagnostics = options.diagnostics;
+		this.environmentReason = options.environmentReason ?? classifyCommandEnvironmentReason(options.cause);
+		this.exitCode = details.exitCode;
+		this.stage = options.stage;
+		this.stderr = details.stderr;
+		this.stdout = details.stdout;
+		this.unitName = options.unitName;
+		this.unitPath = options.unitPath;
+	}
+};
+var UnitLogsReadError = class extends SystemdTsError {
+	args;
+	command;
+	environmentReason;
+	exitCode;
+	reason;
+	stage;
+	stderr;
+	stdout;
+	unitName;
+	unitPath;
+	constructor(message, options = {}) {
+		super(`SYSTEMD_TS_UNIT_LOGS`, message, options);
+		const details = extractCommandErrorDetails(options.cause);
+		this.args = options.args;
+		this.command = options.command;
+		this.environmentReason = options.environmentReason ?? classifyCommandEnvironmentReason(options.cause);
+		this.exitCode = details.exitCode;
+		this.reason = options.reason;
+		this.stage = options.stage;
+		this.stderr = details.stderr;
+		this.stdout = details.stdout;
+		this.unitName = options.unitName;
+		this.unitPath = options.unitPath;
+	}
+};
+var NotifySendError = class extends SystemdTsError {
+	args;
+	command;
+	environmentReason;
+	exitCode;
+	reason;
+	stage;
+	stderr;
+	stdout;
+	constructor(message, options = {}) {
+		super(`SYSTEMD_TS_NOTIFY_SEND`, message, options);
+		const details = extractCommandErrorDetails(options.cause);
+		this.args = options.args;
+		this.command = options.command;
+		this.environmentReason = options.environmentReason ?? classifyCommandEnvironmentReason(options.cause);
+		this.exitCode = details.exitCode;
+		this.reason = options.reason;
+		this.stage = options.stage;
+		this.stderr = details.stderr;
+		this.stdout = details.stdout;
+	}
+};
+var SystemctlCommandError = class extends SystemdTsError {
+	args;
+	command;
+	environmentReason;
+	exitCode;
+	operation;
+	reason;
+	stage;
+	stderr;
+	stdout;
+	constructor(message, options = {}) {
+		super(`SYSTEMD_TS_SYSTEMCTL`, message, options);
+		const details = extractCommandErrorDetails(options.cause);
+		this.args = options.args;
+		this.command = options.command;
+		this.environmentReason = options.environmentReason ?? classifyCommandEnvironmentReason(options.cause);
+		this.exitCode = details.exitCode;
+		this.operation = options.operation;
+		this.reason = options.reason;
+		this.stage = options.stage;
+		this.stderr = details.stderr;
+		this.stdout = details.stdout;
+	}
+};
+function classifyCommandEnvironmentReason(cause) {
+	if (cause === null || typeof cause !== `object`) return;
+	const record = cause;
+	if (record[`code`] === `ENOENT`) return `missing-command`;
+	if (record[`code`] === `EACCES` || record[`code`] === `EPERM`) return `permission-denied`;
+	const combinedOutput = [record[`stderr`], record[`stdout`]].filter((value) => typeof value === `string` && value.length > 0).join(`\n`);
+	if (combinedOutput.includes(`Failed to connect to bus`) || combinedOutput.includes(`System has not been booted with systemd`) || combinedOutput.includes(`Failed to get D-Bus connection`)) return `manager-unavailable`;
+}
+function classifyMaterializationReason(cause) {
+	if (cause === null || typeof cause !== `object`) return;
+	const record = cause;
+	if (record[`code`] === `EACCES` || record[`code`] === `EPERM` || record[`code`] === `EROFS`) return `permission-denied`;
+	if (record[`code`] === `EEXIST` || record[`code`] === `ENOTDIR` || record[`code`] === `EISDIR`) return `invalid-unit-directory`;
+	return `file-system-failed`;
+}
+function extractCommandErrorDetails(cause) {
+	if (cause === null || typeof cause !== `object`) return {
+		exitCode: void 0,
+		stderr: void 0,
+		stdout: void 0
+	};
+	const record = cause;
+	return {
+		exitCode: typeof record[`code`] === `number` ? record[`code`] : void 0,
+		stderr: typeof record[`stderr`] === `string` ? record[`stderr`] : void 0,
+		stdout: typeof record[`stdout`] === `string` ? record[`stdout`] : void 0
+	};
+}
+//#endregion
+//#region src/main/executable.ts
+const currentModulePath = fileURLToPath(import.meta.url);
+/**
+* An immutable description of a runnable module entrypoint that can be used in
+* executable-valued systemd unit directives.
+*
+* `Executable` captures three pieces of information:
+* - the absolute runtime binary that should launch the module
+* - the absolute path to the module itself
+* - any additional arguments that should be passed after the module path
+*
+* Most consumers will create one via {@link defineExecutable} and then pass it
+* into a {@link SystemdService} directive such as `ExecStart`, `ExecStop`, or
+* `ExecReload`.
+*/
+var Executable = class {
+	/** Additional arguments passed after the module path. */
+	args;
+	/** Inference issue captured when no explicit module path was provided. */
+	inferenceError;
+	/** Absolute path to the module that should be executed. */
+	modulePath;
+	/** Absolute path to the runtime binary that should launch the module. */
+	runtimeEntrypoint;
+	/**
+	* Creates an executable description.
+	*
+	* When `modulePath` is omitted, the calling module is inferred from the
+	* current stack so `defineExecutable()` can be used inline from the module
+	* that should become runnable.
+	*
+	* When `runtimeEntrypoint` is omitted, the current process executable is
+	* used. This works well for the common case where the same runtime that is
+	* evaluating your module should also be used by systemd.
+	*/
+	constructor(options = {}) {
+		this.runtimeEntrypoint = options.runtimeEntrypoint ?? process.execPath;
+		const inferredModulePath = options.modulePath ?? tryInferCallerModulePath();
+		this.inferenceError = inferredModulePath === void 0 && options.modulePath === void 0 ? new ExecutableInferenceError() : void 0;
+		this.modulePath = inferredModulePath ?? ``;
+		this.args = Object.freeze([...options.args ?? []]);
+		Object.freeze(this);
+	}
+	/**
+	* Returns the executable as raw command parts.
+	*
+	* The first element is always the runtime entrypoint, followed by the module
+	* path and any configured arguments.
+	*/
+	toCommandParts() {
+		if (this.inferenceError !== void 0) return {
+			ok: false,
+			error: this.inferenceError
+		};
+		return {
+			ok: true,
+			value: [
+				this.runtimeEntrypoint,
+				this.modulePath,
+				...this.args
+			]
+		};
+	}
+	/**
+	* Renders the executable as a shell-quoted command string suitable for
+	* executable-valued systemd directives such as `ExecStart=`.
+	*/
+	toExecStart() {
+		const commandParts = this.toCommandParts();
+		if (!commandParts.ok) return commandParts;
+		return {
+			ok: true,
+			value: commandParts.value.map(shellQuote).join(` `)
+		};
+	}
+};
+/**
+* Defines a module as a runnable executable and returns its immutable
+* `Executable` description.
+*
+* This helper is designed for the pattern:
+*
+* ```ts
+* export default defineExecutable(async () => {
+*   // do work here
+* });
+* ```
+*
+* When the defining module is executed as the main entrypoint, `fn` is invoked.
+* When the module is merely imported, `fn` is not run and only the executable
+* description is returned.
+*
+* Pass `options.runtimeEntrypoint` to override the default runtime binary when
+* the current process is not the exact runtime you want systemd to use.
+*/
+function defineExecutable(fn, options = {}) {
+	const executable = new Executable(options);
+	if (executable.inferenceError === void 0 && isMainModule(executable.modulePath)) Promise.resolve(fn()).catch((error) => {
+		process.exitCode = 1;
+		throw error;
+	});
+	return executable;
+}
+function tryInferCallerModulePath() {
+	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;
+	}
+}
+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;
+	}
+}
+//#endregion
+//#region src/main/internal.ts
+var internal_exports = /* @__PURE__ */ __exportAll({
+	cloneUnitSection: () => cloneUnitSection,
+	defaultCommandExecutor: () => defaultCommandExecutor,
+	defaultUnitDirForScope: () => defaultUnitDirForScope,
+	extractCommandOutput: () => extractCommandOutput,
+	fileExists: () => fileExists,
+	freezeUnitOptions: () => freezeUnitOptions,
+	normalizeUnitName: () => normalizeUnitName,
+	parseStartStatus: () => parseStartStatus,
+	renderUnitFile: () => renderUnitFile,
+	resolveTimerTargetUnit: () => resolveTimerTargetUnit,
+	sendNotify: () => sendNotify,
+	validateServiceSection: () => validateServiceSection
+});
+const EXEC_DIRECTIVE_KEYS = [
+	`ExecCondition`,
+	`ExecReload`,
+	`ExecReloadPost`,
+	`ExecStart`,
+	`ExecStartPost`,
+	`ExecStartPre`,
+	`ExecStop`,
+	`ExecStopPost`
+];
+const execFileAsync = promisify(execFile);
+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 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 EXEC_DIRECTIVE_KEYS) {
+		const validation = assertAbsoluteExecValue(key, service[key]);
+		if (!validation.ok) return validation;
+	}
+	return {
+		ok: true,
+		value: void 0
+	};
+}
+function parseStartStatus(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) {
+	try {
+		const renderedSections = sections.flatMap(([sectionName, section]) => {
+			if (section === void 0) return [];
+			const lines = [];
+			for (const [key, value] of Object.entries(section)) {
+				if (value === void 0) continue;
+				if (isUnitValueList(value)) {
+					for (const entry of value) {
+						const rendered = stringifyUnitValue(entry);
+						if (!rendered.ok) throw rendered.error;
+						lines.push(`${key}=${rendered.value}`);
+					}
+					continue;
+				}
+				const rendered = stringifyUnitValue(value);
+				if (!rendered.ok) throw rendered.error;
+				lines.push(`${key}=${rendered.value}`);
+			}
+			if (lines.length === 0) return [];
+			return [
+				`[${sectionName}]`,
+				...lines,
+				``
+			];
+		}).join(`\n`);
+		return {
+			ok: true,
+			value: renderedSections.endsWith(`\n`) ? renderedSections : `${renderedSections}\n`
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof ExecutableInferenceError ? error : new ExecutableInferenceError({ cause: error })
+		};
+	}
+}
+async function defaultCommandExecutor(command, args, options = {}) {
+	const result = await execFileAsync(command, [...args], options.env === void 0 ? {} : { env: {
+		...process.env,
+		...options.env
+	} });
+	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 = [`--no-block`, 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) {
+		try {
+			await options.executor(`systemd-notify`, args, options.socketPath === void 0 ? {} : { env: { NOTIFY_SOCKET: options.socketPath } });
+		} catch (cause) {
+			throw new NotifySendError(`Failed to send systemd notification through the configured executor`, {
+				args,
+				cause,
+				command: `systemd-notify`,
+				reason: `executor-failed`,
+				stage: `executor`
+			});
+		}
+		return;
+	}
+	try {
+		await execFileAsync(`systemd-notify`, args, { env: {
+			...process.env,
+			...options.socketPath === void 0 ? {} : { NOTIFY_SOCKET: options.socketPath }
+		} });
+	} catch (cause) {
+		throw new NotifySendError(`Failed to send systemd notification with systemd-notify`, {
+			args,
+			cause,
+			command: `systemd-notify`,
+			reason: `systemd-notify-failed`,
+			stage: `systemd-notify`
+		});
+	}
+}
+function extractCommandOutput(cause) {
+	if (cause === null || typeof cause !== `object`) return;
+	const record = cause;
+	const stdout = typeof record[`stdout`] === `string` ? record[`stdout`] : void 0;
+	const stderr = typeof record[`stderr`] === `string` ? record[`stderr`] : void 0;
+	if (stdout === void 0 && stderr === void 0) return;
+	return {
+		stderr: stderr ?? ``,
+		stdout: stdout ?? ``
+	};
+}
+function hasServiceSection(options) {
+	return `service` in options;
+}
+function hasTimerSection(options) {
+	return `timer` in options;
+}
+function assertAbsoluteExecValue(key, value) {
+	if (isUnitValueList(value)) {
+		for (const entry of value) {
+			const validation = assertAbsoluteExecEntry(key, entry);
+			if (!validation.ok) return validation;
+		}
+		return {
+			ok: true,
+			value: void 0
+		};
+	}
+	return assertAbsoluteExecEntry(key, value);
+}
+function assertAbsoluteExecEntry(key, value) {
+	if (typeof value === `string` && value.length > 0 && !isAbsoluteExecCommand(value)) return {
+		ok: false,
+		error: new InvalidExecDirectiveError(key)
+	};
+	if (value instanceof Executable && !value.runtimeEntrypoint.startsWith(`/`)) return {
+		ok: false,
+		error: new InvalidExecDirectiveError(key)
+	};
+	return {
+		ok: true,
+		value: void 0
+	};
+}
+function stringifyUnitValue(value) {
+	if (value instanceof Executable) return value.toExecStart();
+	if (typeof value === `boolean`) return {
+		ok: true,
+		value: value ? `true` : `false`
+	};
+	return {
+		ok: true,
+		value: String(value)
+	};
+}
+function isUnitValueList(value) {
+	return Array.isArray(value);
+}
+function isAbsoluteExecCommand(value) {
+	let index = 0;
+	let hasPrivilegePrefix = false;
+	while (index < value.length) {
+		const prefix = value[index];
+		if (prefix === `@` || prefix === `-` || prefix === `:`) {
+			index += 1;
+			continue;
+		}
+		if (prefix === `+`) {
+			if (hasPrivilegePrefix) return false;
+			hasPrivilegePrefix = true;
+			index += 1;
+			continue;
+		}
+		if (prefix === `!`) {
+			if (hasPrivilegePrefix) return false;
+			hasPrivilegePrefix = true;
+			index += value[index + 1] === `!` ? 2 : 1;
+			continue;
+		}
+		break;
+	}
+	return value[index] === `/`;
+}
+//#endregion
+//#region src/main/notify.ts
+/**
+* Helpers for sending `sd_notify` state updates to systemd.
+*
+* These helpers send notification payloads to the socket identified by
+* `NOTIFY_SOCKET`, or to `options.socketPath` when one is provided explicitly.
+* They are useful both in real services and in tests that want to observe
+* readiness or watchdog traffic directly.
+*
+* Source:
+* - https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html
+* - https://www.freedesktop.org/software/systemd/man/latest/systemd-notify.html
+*/
+const notify = {
+	/**
+	* Sends `READY=1` to systemd.
+	*
+	* Use this when a `Type=notify` service has completed its startup work and is
+	* ready to be considered fully started. If `options.status` is provided, it is
+	* sent as an additional `STATUS=...` field.
+	*/
+	async ready(options = {}) {
+		try {
+			await sendNotify(`READY=1`, options);
+			return {
+				ok: true,
+				value: void 0
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: error instanceof NotifySendError ? error : new NotifySendError(`Failed to send READY=1 notification`, {
+					cause: error,
+					stage: `ready`
+				})
+			};
+		}
+	},
+	/**
+	* Sends `WATCHDOG=1` to systemd.
+	*
+	* Use this when a service configured with `WatchdogSec=` needs to emit a
+	* watchdog heartbeat. If `options.pid` is provided, it is sent as
+	* `MAINPID=...`, and `options.status` is forwarded as `STATUS=...`.
+	*/
+	async watchdog(options = {}) {
+		try {
+			await sendNotify(`WATCHDOG=1`, options);
+			return {
+				ok: true,
+				value: void 0
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: error instanceof NotifySendError ? error : new NotifySendError(`Failed to send WATCHDOG=1 notification`, {
+					cause: error,
+					stage: `watchdog`
+				})
+			};
+		}
+	}
+};
+//#endregion
+//#region src/main/systemd-service.ts
+/**
+* An immutable definition of a `.service` unit.
+*
+* `SystemdService` is a pure value object: it captures the intended unit name
+* and section contents, but it does not write files or talk to `systemd`
+* directly. Operational actions such as installation or startup belong on
+* {@link Systemd}.
+*
+* Source:
+* - https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html
+*/
+var SystemdService = class {
+	/** Optional `[Install]` section for enable-time relationships. */
+	install;
+	/** The normalized base unit name, without the `.service` suffix. */
+	name;
+	/** The fully frozen original options used to construct this service. */
+	options;
+	/** The `[Service]` section payload. */
+	service;
+	/** Optional `[Unit]` section metadata and dependency configuration. */
+	unit;
+	/**
+	* Creates an immutable service definition.
+	*
+	* The constructor preserves literal types where possible and rejects unknown
+	* directive names within the provided sections, while still allowing custom
+	* `X-...` extension directives.
+	*/
+	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);
+	}
+	/** The canonical unit filename, including the `.service` suffix. */
+	get filename() {
+		return `${this.name}.service`;
+	}
+	/**
+	* Renders the service as a complete unit file.
+	*
+	* Rendering also validates executable-valued directives such as `ExecStart`
+	* and `ExecStop`, ensuring they use absolute runtime entrypoints as required
+	* by systemd.
+	*/
+	render() {
+		const validation = validateServiceSection(this.service);
+		if (!validation.ok) return validation;
+		return renderUnitFile([
+			[`Unit`, this.unit],
+			[`Service`, this.service],
+			[`Install`, this.install]
+		]);
+	}
+};
+//#endregion
+//#region src/main/systemd-timer.ts
+/**
+* An immutable definition of a `.timer` unit.
+*
+* Like {@link SystemdService}, this is a pure value object. It models the timer
+* configuration and its attachment target, but does not write files or interact
+* with the service manager directly.
+*
+* Source:
+* - https://www.freedesktop.org/software/systemd/man/latest/systemd.timer.html
+*/
+var SystemdTimer = class {
+	/** Optional `[Install]` section for enable-time relationships. */
+	install;
+	/** The normalized base unit name, without the `.timer` suffix. */
+	name;
+	/** The fully frozen original options used to construct this timer. */
+	options;
+	/** The attached service basename inferred from `targetUnit`. */
+	targetServiceName;
+	/** The unit name this timer activates, explicit or implicit. */
+	targetUnit;
+	/** The `[Timer]` section payload. */
+	timer;
+	/** Optional `[Unit]` section metadata and dependency configuration. */
+	unit;
+	/**
+	* Creates an immutable timer definition.
+	*
+	* If no explicit `timer.Unit` is provided, the target defaults to the service
+	* with the same basename, matching systemd's native timer behavior.
+	*/
+	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);
+	}
+	/** The canonical unit filename, including the `.timer` suffix. */
+	get filename() {
+		return `${this.name}.timer`;
+	}
+	/** Renders the timer as a complete unit file. */
+	render() {
+		return renderUnitFile([
+			[`Unit`, this.unit],
+			[`Timer`, this.timer],
+			[`Install`, this.install]
+		]);
+	}
+};
+//#endregion
+//#region src/main/systemctl.ts
+/**
+* A TypeScript-first client for invoking `systemctl` with structured argument
+* vectors instead of shell-composed command strings.
+*
+* This lower-level primitive is useful both on its own and as the subprocess
+* transport underneath higher-level abstractions such as {@link Systemd}.
+*/
+var Systemctl = class {
+	/** Command executor used for `systemctl` subprocesses. */
+	executor;
+	/** The target manager scope, either `system` or `user`. */
+	scope;
+	constructor(options = {}) {
+		this.scope = options.scope ?? `system`;
+		this.executor = options.executor ?? defaultCommandExecutor;
+		Object.freeze(this);
+	}
+	/** Reloads the targeted systemd manager. */
+	async daemonReload() {
+		return this.run(`daemon-reload`);
+	}
+	/** Enables a unit by filename. */
+	async enable(unit) {
+		return this.run(`enable`, unit);
+	}
+	/** Disables a unit by filename. */
+	async disable(unit) {
+		return this.run(`disable`, unit);
+	}
+	/** Links a unit file path into the targeted manager. */
+	async link(path) {
+		return this.run(`link`, path);
+	}
+	/**
+	* Checks the install-time enablement state of a unit file.
+	*
+	* Source:
+	* - systemd v260.1, `systemctl(1)`
+	*/
+	async isEnabled(unit, options = {}) {
+		const output = await this.run(`is-enabled`, ...options.full ? [`--full`] : [], ...options.quiet ? [`--quiet`] : [], unit);
+		if (!output.ok) return output;
+		return ok$1(firstNonEmptyOutputLine(output.value));
+	}
+	/**
+	* Checks the runtime active state of a unit.
+	*
+	* Unless `quiet` is set, this returns the state string printed by
+	* `systemctl is-active`.
+	*/
+	async isActive(unit, options = {}) {
+		const output = await this.run(`is-active`, ...options.quiet ? [`--quiet`] : [], unit);
+		if (!output.ok) return output;
+		return ok$1(firstNonEmptyOutputLine(output.value));
+	}
+	/**
+	* Checks whether a unit is in the failed state.
+	*
+	* Unless `quiet` is set, this returns the state string printed by
+	* `systemctl is-failed`.
+	*/
+	async isFailed(unit, options = {}) {
+		const output = await this.run(`is-failed`, ...options.quiet ? [`--quiet`] : [], unit);
+		if (!output.ok) return output;
+		return ok$1(firstNonEmptyOutputLine(output.value));
+	}
+	/**
+	* Queries the overall manager state reported by `systemctl is-system-running`.
+	*
+	* Source:
+	* - systemd v260.1, `systemctl(1)`
+	*/
+	async isSystemRunning(options = {}) {
+		const output = await this.run(`is-system-running`, ...options.wait ? [`--wait`] : []);
+		if (!output.ok) return output;
+		return ok$1(firstNonEmptyOutputLine(output.value));
+	}
+	/**
+	* Queries `systemctl show` for a unit.
+	*
+	* When `properties` are provided, only those properties are requested.
+	*/
+	async show(unit, options = {}) {
+		const propertyFlag = options.properties === void 0 || options.properties.length === 0 ? [] : [`--property=${options.properties.join(`,`)}`];
+		return this.run(`show`, unit, ...propertyFlag);
+	}
+	/**
+	* Queries `systemctl show` and parses the result into a key-value object.
+	*
+	* Properties are returned exactly as printed by `systemctl show`.
+	*/
+	async showProperties(unit, options = {}) {
+		const output = await this.show(unit, options);
+		if (!output.ok) return output;
+		return ok$1(parseSystemctlShowOutput(output.value.stdout));
+	}
+	/**
+	* Queries the standard status-related `show` properties for a unit and
+	* returns a parsed snapshot.
+	*/
+	async showStatus(unit) {
+		return this.showServiceStatus(unit);
+	}
+	/**
+	* Queries the standard service-status `show` properties for a service unit
+	* and returns a parsed snapshot.
+	*/
+	async showServiceStatus(unit) {
+		const output = await this.show(unit, { properties: [
+			`Id`,
+			`ActiveState`,
+			`SubState`,
+			`Result`,
+			`ExecMainStatus`
+		] });
+		if (!output.ok) return output;
+		return ok$1(parseStartStatus(unit, output.value.stdout));
+	}
+	/**
+	* Queries `systemctl list-timers` and returns the observed JSON payload
+	* shape directly, with raw integer timestamps left intact.
+	*/
+	async listTimers(options = {}) {
+		const args = [
+			`list-timers`,
+			...options.all ? [`--all`] : [],
+			...options.noPager ?? true ? [`--no-pager`] : [],
+			`--output=json`,
+			...options.patterns ?? []
+		];
+		const output = await this.run(...args);
+		if (!output.ok) return output;
+		try {
+			return ok$1(JSON.parse(output.value.stdout));
+		} catch (cause) {
+			return err$1(new SystemctlCommandError(`Failed to parse JSON output from systemctl list-timers`, {
+				args: [...this.scopeArgs(), ...args],
+				cause,
+				command: `systemctl`,
+				operation: `list-timers`,
+				reason: `invalid-json`
+			}));
+		}
+	}
+	/** Starts a unit by filename. */
+	async start(unit) {
+		return this.run(`start`, unit);
+	}
+	/** Stops a unit by filename. */
+	async stop(unit) {
+		return this.run(`stop`, unit);
+	}
+	/** Restarts a unit by filename. */
+	async restart(unit) {
+		return this.run(`restart`, unit);
+	}
+	/**
+	* Resets the failed state for matching units, or for all units when no
+	* patterns are provided.
+	*/
+	async resetFailed(patterns = []) {
+		return this.run(`reset-failed`, ...patterns);
+	}
+	/**
+	* Queries `systemctl status` for a unit.
+	*
+	* This is primarily a human-oriented command and is best paired with
+	* `show()` when structured state is needed.
+	*/
+	async status(unit, options = {}) {
+		const args = [`status`, unit];
+		if (options.noPager ?? true) args.push(`--no-pager`);
+		if (options.lines !== void 0) args.push(`--lines`, String(options.lines));
+		return this.run(...args);
+	}
+	/** Executes a raw `systemctl` invocation with scope-aware arguments. */
+	async run(...args) {
+		const scopedArgs = [...this.scopeArgs(), ...args];
+		try {
+			return ok$1(await this.executor(`systemctl`, scopedArgs));
+		} catch (cause) {
+			return err$1(new SystemctlCommandError(`Failed to run systemctl ${args[0] ?? `command`}`, {
+				args: scopedArgs,
+				cause,
+				command: `systemctl`,
+				operation: args[0],
+				reason: `executor-failed`
+			}));
+		}
+	}
+	scopeArgs() {
+		return this.scope === `user` ? [`--user`] : [];
+	}
+};
+function ok$1(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err$1(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+function parseSystemctlShowOutput(output) {
+	return Object.freeze(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)];
+	})));
+}
+function firstNonEmptyOutputLine(output) {
+	return [output.stdout, output.stderr].flatMap((value) => value.split(`\n`)).map((value) => value.trim()).find((value) => value.length > 0) ?? ``;
+}
+//#endregion
+//#region src/main/systemd.ts
+/**
+* A successful systemd unit materialization.
+*
+* It records the target directory and the on-disk path associated with each
+* materialized unit.
+*/
+var SystemdMaterialization = class {
+	/** The directory units were written into. */
+	directory;
+	/** The materialized units together with their resolved on-disk paths. */
+	materialized;
+	constructor(directory, materialized) {
+		this.directory = directory;
+		this.materialized = Object.freeze([...materialized]);
+		Object.freeze(this);
+	}
+};
+/**
+* A configured interface to a specific systemd environment.
+*
+* `Systemd` combines unit-file materialization with a command execution
+* strategy. It knows which scope it is targeting, where unit files should be
+* written, and how `systemctl` should be invoked.
+*
+* This abstraction is intentionally close to `systemctl` concepts while still
+* accepting full unit definitions instead of loose unit-name strings.
+*/
+var Systemd = class {
+	/** Command executor used for `systemctl` and related subprocess calls. */
+	executor;
+	/** Whether units should be linked into systemd before manager operations. */
+	linkUnits;
+	/** The target manager scope, either `system` or `user`. */
+	scope;
+	/** The low-level `systemctl` client for this configured target. */
+	systemctl;
+	/** Higher-level `systemd-ts` upkeep helpers for application-owned units. */
+	ts;
+	/** The directory used when materializing unit files. */
+	unitDir;
+	/**
+	* Creates a configured `Systemd` facade.
+	*
+	* By default, this targets the system scope and `/etc/systemd/system`. Use
+	* `scope: "user"` or an explicit `unitDir` to target a different manager or
+	* unit-file location.
+	*/
+	constructor(options = {}) {
+		this.scope = options.scope ?? `system`;
+		this.unitDir = options.unitDir ?? defaultUnitDirForScope(this.scope);
+		this.linkUnits = options.linkUnits ?? false;
+		this.executor = options.executor ?? defaultCommandExecutor;
+		this.systemctl = new Systemctl({
+			executor: this.executor,
+			scope: this.scope
+		});
+		this.ts = new SystemdTs(this);
+		Object.freeze(this);
+	}
+	/**
+	* Renders and writes one or more units into this instance's `unitDir`.
+	*
+	* This is intentionally a file-materialization step. It does not enable or
+	* start the units on its own.
+	*/
+	async materialize(...units) {
+		return this.materializeUnits(units);
+	}
+	/**
+	* Enables one or more units via `systemctl enable`.
+	*
+	* When `linkUnits` is enabled, this first links materialized unit files into the
+	* target manager and reloads systemd so the units are visible before the
+	* enable operation runs.
+	*/
+	async enable(...units) {
+		if (units.length === 0) return err(new NoUnitsProvidedError(`Systemd.enable()`));
+		const scopeArgs = this.scopeArgs();
+		try {
+			await this.prepareUnits(scopeArgs, units, `enable`);
+		} catch (cause) {
+			if (cause instanceof UnitEnableError) return err(cause);
+			return err(new UnitEnableError(`Failed to prepare units for enable`, {
+				cause,
+				stage: `prepare`,
+				unitName: units[0]?.filename
+			}));
+		}
+		for (const unit of units) {
+			const args = [
+				...scopeArgs,
+				`enable`,
+				unit.filename
+			];
+			const enabled = await this.systemctl.enable(unit.filename);
+			if (!enabled.ok) {
+				const errorOptions = {
+					args,
+					cause: enabled.error,
+					command: `systemctl`,
+					stage: `enable`,
+					unitName: unit.filename,
+					...enabled.error.environmentReason === void 0 ? {} : { environmentReason: enabled.error.environmentReason }
+				};
+				return err(new UnitEnableError(`Failed to enable ${unit.filename}`, errorOptions));
+			}
+		}
+		return ok(void 0);
+	}
+	/**
+	* Starts a unit and returns a parsed `systemctl show` snapshot of its final
+	* observed state.
+	*
+	* For oneshot services, a successful result commonly means `ActiveState` is
+	* already back to `inactive` by the time the status snapshot is collected.
+	*/
+	async start(unit) {
+		const scopeArgs = this.scopeArgs();
+		try {
+			await this.prepareUnits(scopeArgs, [unit], `start`);
+		} catch (cause) {
+			if (cause instanceof UnitStartError) return err(cause);
+			return err(new UnitStartError(`Failed to prepare ${unit.filename} for start`, {
+				cause,
+				diagnostics: await this.collectStartDiagnostics(scopeArgs, unit.filename),
+				stage: `prepare`,
+				unitName: unit.filename
+			}));
+		}
+		const startArgs = [
+			...scopeArgs,
+			`start`,
+			unit.filename
+		];
+		const started = await this.systemctl.start(unit.filename);
+		if (!started.ok) {
+			const errorOptions = {
+				args: startArgs,
+				cause: started.error,
+				command: `systemctl`,
+				diagnostics: await this.collectStartDiagnostics(scopeArgs, unit.filename),
+				stage: `start`,
+				unitName: unit.filename,
+				...started.error.environmentReason === void 0 ? {} : { environmentReason: started.error.environmentReason }
+			};
+			return err(new UnitStartError(`Failed to start ${unit.filename}`, errorOptions));
+		}
+		const status = await this.systemctl.showServiceStatus(unit.filename);
+		if (!status.ok) {
+			const errorOptions = {
+				args: [
+					...scopeArgs,
+					`show`,
+					unit.filename,
+					`--property=Id,ActiveState,SubState,Result,ExecMainStatus`
+				],
+				cause: status.error,
+				command: `systemctl`,
+				diagnostics: await this.collectStartDiagnostics(scopeArgs, unit.filename),
+				stage: `show-status`,
+				unitName: unit.filename,
+				...status.error.environmentReason === void 0 ? {} : { environmentReason: status.error.environmentReason }
+			};
+			return err(new UnitStartError(`Started ${unit.filename} but failed to query its status`, errorOptions));
+		}
+		return ok(status.value);
+	}
+	/**
+	* Reads recent output for a managed unit.
+	*
+	* If the unit is configured with file-backed `StandardOutput` or
+	* `StandardError`, this reads directly from that file. Otherwise it falls back
+	* to `systemctl status --lines ...`.
+	*/
+	async logs(unit, options) {
+		const fileLogPath = resolveUnitLogPath(unit);
+		if (fileLogPath !== void 0) try {
+			return ok(tailLines(await readFile(fileLogPath, `utf8`), options?.lines ?? 50));
+		} catch (cause) {
+			return err(new UnitLogsReadError(`Failed to read logs for ${unit.filename} from ${fileLogPath}`, {
+				cause,
+				reason: isMissingPathError(cause) ? `missing-log-file` : `log-file-read-failed`,
+				stage: `read-log-file`,
+				unitName: unit.filename,
+				unitPath: fileLogPath
+			}));
+		}
+		const scopeArgs = this.scopeArgs();
+		const lines = options?.lines ?? 50;
+		const logs = await this.systemctl.status(unit.filename, { lines });
+		if (logs.ok) return ok(joinCommandOutput(logs.value));
+		const errorOutput = extractCommandOutput(logs.error);
+		if (errorOutput !== void 0) return ok(joinCommandOutput(errorOutput));
+		const args = [
+			...scopeArgs,
+			`status`,
+			unit.filename,
+			`--no-pager`,
+			`--lines`,
+			String(lines)
+		];
+		return err(new UnitLogsReadError(`Failed to query logs for ${unit.filename} from systemctl status`, {
+			args,
+			cause: logs.error,
+			command: `systemctl`,
+			reason: `status-command-failed`,
+			stage: `status`,
+			unitName: unit.filename
+		}));
+	}
+	/** Returns the on-disk unit-file path this instance uses for the given unit. */
+	pathFor(unit) {
+		return join(this.unitDir, unit.filename);
+	}
+	async prepareUnits(scopeArgs, units, operation) {
+		if (this.linkUnits) {
+			const linkPaths = await this.collectLinkPaths(units);
+			for (const path of linkPaths) {
+				const args = [
+					...scopeArgs,
+					`link`,
+					path
+				];
+				const linked = await this.systemctl.link(path);
+				if (!linked.ok) {
+					const linkedUnit = units.find((candidate) => this.pathFor(candidate) === path);
+					const errorContext = {
+						args,
+						cause: linked.error,
+						command: `systemctl`,
+						stage: `link`,
+						unitPath: path,
+						...linked.error.environmentReason === void 0 ? {} : { environmentReason: linked.error.environmentReason },
+						...linkedUnit === void 0 ? {} : { unitName: linkedUnit.filename }
+					};
+					throw operation === `enable` ? new UnitEnableError(`Failed to link ${path} before enable`, errorContext) : new UnitStartError(`Failed to link ${path} before start`, errorContext);
+				}
+			}
+		}
+		const args = [...scopeArgs, `daemon-reload`];
+		const reloaded = await this.systemctl.daemonReload();
+		if (!reloaded.ok) {
+			const errorContext = {
+				args,
+				cause: reloaded.error,
+				command: `systemctl`,
+				stage: `daemon-reload`,
+				...reloaded.error.environmentReason === void 0 ? {} : { environmentReason: reloaded.error.environmentReason },
+				...units[0]?.filename === void 0 ? {} : { unitName: units[0].filename }
+			};
+			throw operation === `enable` ? new UnitEnableError(`Failed to reload systemd before enable`, errorContext) : new UnitStartError(`Failed to reload systemd before start`, errorContext);
+		}
+	}
+	scopeArgs() {
+		return this.scope === `user` ? [`--user`] : [];
+	}
+	async collectStartDiagnostics(scopeArgs, unitName) {
+		const diagnostics = {};
+		const showArgs = [
+			...scopeArgs,
+			`show`,
+			unitName,
+			`--property=Id,ActiveState,SubState,Result,ExecMainStatus`
+		];
+		const show = await this.tryBestEffortCommand(`systemctl`, showArgs);
+		if (show !== void 0) {
+			const showOutput = joinCommandOutput(show);
+			if (showOutput.length > 0) diagnostics.showOutput = showOutput;
+			if (show.stdout.length > 0) diagnostics.showStatus = parseStartStatus(unitName, show.stdout);
+		}
+		const statusArgs = [
+			...scopeArgs,
+			`status`,
+			unitName,
+			`--no-pager`,
+			`--lines`,
+			`20`
+		];
+		const status = await this.tryBestEffortCommand(`systemctl`, statusArgs);
+		if (status !== void 0) {
+			const statusOutput = joinCommandOutput(status);
+			if (statusOutput.length > 0) diagnostics.statusOutput = statusOutput;
+		}
+		return diagnostics;
+	}
+	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];
+	}
+	async materializeUnits(units) {
+		if (units.length === 0) return err(new NoUnitsProvidedError(`Systemd.materialize()`));
+		try {
+			await writeUnitDirectory(this.unitDir);
+		} catch (cause) {
+			const reason = classifyMaterializationReason(cause);
+			return err(new UnitMaterializationError(`Failed to create unit directory ${this.unitDir}`, {
+				cause,
+				operation: `create-directory`,
+				...reason === void 0 ? {} : { reason },
+				unitPath: this.unitDir
+			}));
+		}
+		const materialized = [];
+		for (const unit of units) {
+			const path = join(this.unitDir, unit.filename);
+			const rendered = unit.render();
+			if (!rendered.ok) return err(rendered.error);
+			try {
+				await writeFile(path, rendered.value, `utf8`);
+			} catch (cause) {
+				if (cause instanceof InvalidExecDirectiveError) return err(cause);
+				const reason = classifyMaterializationReason(cause);
+				return err(new UnitMaterializationError(`Failed to materialize ${unit.filename} into ${path}`, {
+					cause,
+					operation: `write-file`,
+					...reason === void 0 ? {} : { reason },
+					unitName: unit.filename,
+					unitPath: path
+				}));
+			}
+			materialized.push({
+				path,
+				unit
+			});
+		}
+		return ok(new SystemdMaterialization(this.unitDir, materialized));
+	}
+	async tryBestEffortCommand(command, args) {
+		try {
+			return await this.executor(command, args);
+		} catch (cause) {
+			const output = extractCommandOutput(cause);
+			if (output !== void 0) return output;
+			return;
+		}
+	}
+};
+/**
+* Opinionated `systemd-ts` upkeep helpers for application-owned units.
+*
+* This layer is intentionally analogous to a subset of `portablectl`'s
+* ownership workflow, but it operates on regular materialized units instead of
+* portable service images.
+*/
+var SystemdTs = class {
+	systemd;
+	constructor(systemd) {
+		this.systemd = systemd;
+		Object.freeze(this);
+	}
+	async attach(units, options) {
+		if (units.length === 0) return err(new NoUnitsProvidedError(`Systemd.ts.attach()`));
+		const described = await this.describeUnits(units);
+		if (!described.ok) return described;
+		const manifestPath = this.manifestPathFor(options.owner);
+		const prior = await this.readManifest(options.owner);
+		const diff = await this.diffManifest(prior, described.value);
+		const materialized = await this.systemd.materialize(...units);
+		if (!materialized.ok) return materialized;
+		const enabled = [];
+		if (options.enable ?? false) {
+			const result = await this.systemd.enable(...units);
+			if (!result.ok) return result;
+			enabled.push(...units.map((unit) => unit.filename));
+		}
+		const started = [];
+		if (options.start ?? false) for (const unit of units) {
+			const result = await this.systemd.start(unit);
+			if (!result.ok) return result;
+			started.push(unit.filename);
+		}
+		await this.writeManifest(options.owner, described.value);
+		return ok({
+			added: diff.added,
+			directory: this.systemd.unitDir,
+			enabled,
+			manifestPath,
+			owner: options.owner,
+			removed: diff.removed,
+			restarted: [],
+			started,
+			unchanged: diff.unchanged,
+			updated: diff.updated
+		});
+	}
+	async detach(selector, options = {}) {
+		const manifest = await this.readManifest(selector.owner);
+		if (manifest === void 0) return ok({
+			deleted: [],
+			detached: [],
+			disabled: [],
+			owner: selector.owner,
+			stopped: []
+		});
+		const filenames = manifest.units.map((unit) => unit.filename);
+		const deleted = [];
+		const disabled = [];
+		const stopped = [];
+		if (options.stop ?? true) {
+			await this.runSystemctl(`stop`, filenames);
+			stopped.push(...filenames);
+		}
+		if (options.disable ?? true) {
+			await this.runSystemctl(`disable`, filenames);
+			disabled.push(...filenames);
+		}
+		if (options.deleteUnitFiles ?? true) {
+			for (const unit of manifest.units) {
+				await this.removeManagedUnitPath(unit.path);
+				await rm(unit.path, { force: true });
+				deleted.push(unit.filename);
+			}
+			await this.runSystemctl(`daemon-reload`);
+		}
+		await rm(this.manifestPathFor(selector.owner), { force: true });
+		return ok({
+			deleted,
+			detached: filenames,
+			disabled,
+			owner: selector.owner,
+			stopped
+		});
+	}
+	async reattach(units, options) {
+		if (units.length === 0) return err(new NoUnitsProvidedError(`Systemd.ts.reattach()`));
+		const described = await this.describeUnits(units);
+		if (!described.ok) return described;
+		const manifestPath = this.manifestPathFor(options.owner);
+		const prior = await this.readManifest(options.owner);
+		const diff = await this.diffManifest(prior, described.value);
+		if ((options.stopRemoved ?? true) && diff.removed.length > 0) await this.runSystemctl(`stop`, diff.removed);
+		if ((options.disableRemoved ?? true) && diff.removed.length > 0) await this.runSystemctl(`disable`, diff.removed);
+		if ((options.prune ?? true) && prior !== void 0) {
+			for (const unit of prior.units) {
+				if (!diff.removed.includes(unit.filename)) continue;
+				await this.removeManagedUnitPath(unit.path);
+				await rm(unit.path, { force: true });
+			}
+			if (diff.removed.length > 0) await this.runSystemctl(`daemon-reload`);
+		}
+		const materialized = await this.systemd.materialize(...units);
+		if (!materialized.ok) return materialized;
+		const enabled = [];
+		if (options.enable ?? false) {
+			const result = await this.systemd.enable(...units);
+			if (!result.ok) return result;
+			enabled.push(...units.map((unit) => unit.filename));
+		}
+		const restarted = [];
+		if (options.restartUpdated ?? false) {
+			const restartable = units.filter((unit) => diff.updated.includes(unit.filename)).map((unit) => unit.filename);
+			if (restartable.length > 0) {
+				await this.runSystemctl(`restart`, restartable);
+				restarted.push(...restartable);
+			}
+		}
+		const started = [];
+		if (options.start ?? false) for (const unit of units) {
+			if (restarted.includes(unit.filename)) continue;
+			const result = await this.systemd.start(unit);
+			if (!result.ok) return result;
+			started.push(unit.filename);
+		}
+		await this.writeManifest(options.owner, described.value);
+		return ok({
+			added: diff.added,
+			directory: this.systemd.unitDir,
+			enabled,
+			manifestPath,
+			owner: options.owner,
+			removed: diff.removed,
+			restarted,
+			started,
+			unchanged: diff.unchanged,
+			updated: diff.updated
+		});
+	}
+	async describeUnits(units) {
+		const described = [];
+		for (const unit of units) {
+			const rendered = unit.render();
+			if (!rendered.ok) return rendered;
+			described.push({
+				filename: unit.filename,
+				path: this.systemd.pathFor(unit),
+				rendered: rendered.value
+			});
+		}
+		return ok(described);
+	}
+	async diffManifest(prior, desired) {
+		const priorUnits = new Map(prior?.units.map((unit) => [unit.filename, unit.path]) ?? []);
+		const desiredNames = new Set(desired.map((unit) => unit.filename));
+		const added = [];
+		const removed = [...priorUnits.keys()].filter((filename) => !desiredNames.has(filename));
+		const unchanged = [];
+		const updated = [];
+		for (const unit of desired) {
+			const priorPath = priorUnits.get(unit.filename);
+			if (priorPath === void 0) {
+				added.push(unit.filename);
+				continue;
+			}
+			try {
+				if (await readFile(priorPath, `utf8`) === unit.rendered) {
+					unchanged.push(unit.filename);
+					continue;
+				}
+			} catch {
+				added.push(unit.filename);
+				continue;
+			}
+			updated.push(unit.filename);
+		}
+		return {
+			added,
+			removed,
+			unchanged,
+			updated
+		};
+	}
+	async manifestDir() {
+		const directory = join(this.systemd.unitDir, `.systemd-ts`);
+		await mkdir(directory, { recursive: true });
+		return directory;
+	}
+	manifestPathFor(owner) {
+		return join(this.systemd.unitDir, `.systemd-ts`, `${encodeURIComponent(owner)}.json`);
+	}
+	async readManifest(owner) {
+		try {
+			const content = await readFile(this.manifestPathFor(owner), `utf8`);
+			return JSON.parse(content);
+		} catch {
+			return;
+		}
+	}
+	async runSystemctl(action, units = []) {
+		const args = action === `daemon-reload` ? [...this.scopeArgs(), action] : [
+			...this.scopeArgs(),
+			action,
+			...units
+		];
+		await this.systemd.executor(`systemctl`, args);
+	}
+	async removeManagedUnitPath(path) {
+		await this.systemd.executor(`rm`, [`-f`, path]);
+	}
+	scopeArgs() {
+		return this.systemd.scope === `user` ? [`--user`] : [];
+	}
+	async writeManifest(owner, units) {
+		await this.manifestDir();
+		const manifest = {
+			owner,
+			units: units.map((unit) => ({
+				filename: unit.filename,
+				path: unit.path
+			})),
+			version: 1
+		};
+		await writeFile(this.manifestPathFor(owner), JSON.stringify(manifest, null, 2), `utf8`);
+	}
+};
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+function joinCommandOutput(output) {
+	return [output.stdout, output.stderr].filter((value) => value.length > 0).join(`\n`);
+}
+let lazyDefaultSystemd;
+/**
+* Returns the lazily created default `Systemd` instance.
+*
+* The default instance uses the library defaults for scope, unit directory, and
+* command execution.
+*/
+function defaultSystemd() {
+	lazyDefaultSystemd ??= new Systemd();
+	return lazyDefaultSystemd;
+}
+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`);
+}
+function isMissingPathError(cause) {
+	if (cause === null || typeof cause !== `object`) return false;
+	return cause[`code`] === `ENOENT`;
+}
+async function writeUnitDirectory(path) {
+	await mkdir(path, { recursive: true });
+}
+//#endregion
+//#region src/main/index.ts
+/**
+* Internal helpers are exposed for advanced use, but they are not a stable public API.
+* Expect breaking changes here outside the package's normal compatibility guarantees.
+*/
+const Internal = internal_exports;
+//#endregion
+export { SystemdTsError as _, defaultSystemd as a, UnitMaterializationError as b, SystemdService as c, defineExecutable as d, ExecutableInferenceError as f, SystemctlCommandError as g, NotifySendError as h, SystemdTs as i, notify as l, NoUnitsProvidedError as m, Systemd as n, Systemctl as o, InvalidExecDirectiveError as p, SystemdMaterialization as r, SystemdTimer as s, Internal as t, Executable as u, UnitEnableError as v, UnitStartError as x, UnitLogsReadError as y };
+
+//# sourceMappingURL=main-BXq7TQdg.mjs.map