systemd-ts 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -5,6 +5,174 @@ import { execFile } from "node:child_process";
 import { access, mkdir, readFile, 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;
+	}
+};
+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);
 /**
@@ -23,6 +191,8 @@ const currentModulePath = fileURLToPath(import.meta.url);
 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. */
@@ -40,7 +210,9 @@ var Executable = class {
 	*/
 	constructor(options = {}) {
 		this.runtimeEntrypoint = options.runtimeEntrypoint ?? process.execPath;
-		this.modulePath = options.modulePath ?? inferCallerModulePath();
+		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);
 	}
@@ -51,18 +223,30 @@ var Executable = class {
 	* path and any configured arguments.
 	*/
 	toCommandParts() {
-		return [
-			this.runtimeEntrypoint,
-			this.modulePath,
-			...this.args
-		];
+		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() {
-		return this.toCommandParts().map(shellQuote$1).join(` `);
+		const commandParts = this.toCommandParts();
+		if (!commandParts.ok) return commandParts;
+		return {
+			ok: true,
+			value: commandParts.value.map(shellQuote$1).join(` `)
+		};
 	}
 };
 /**
@@ -86,20 +270,19 @@ var Executable = class {
 */
 function defineExecutable(fn, options = {}) {
 	const executable = new Executable(options);
-	if (isMainModule(executable.modulePath)) Promise.resolve(fn()).catch((error) => {
+	if (executable.inferenceError === void 0 && isMainModule(executable.modulePath)) Promise.resolve(fn()).catch((error) => {
 		process.exitCode = 1;
 		throw error;
 	});
 	return executable;
 }
-function inferCallerModulePath() {
+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;
 	}
-	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);
@@ -123,131 +306,15 @@ function normalizeFilePath(path) {
 	}
 }
 //#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() {
-		validateServiceSection(this.service);
-		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/internal.ts
 var internal_exports = /* @__PURE__ */ __exportAll({
-	assertInstallableTogether: () => assertInstallableTogether,
 	cloneUnitSection: () => cloneUnitSection,
 	defaultCommandExecutor: () => defaultCommandExecutor,
 	defaultUnitDirForScope: () => defaultUnitDirForScope,
 	fileExists: () => fileExists,
 	freezeUnitOptions: () => freezeUnitOptions,
 	normalizeUnitName: () => normalizeUnitName,
-	parseStartResult: () => parseStartResult,
+	parseStartStatus: () => parseStartStatus,
 	renderUnitFile: () => renderUnitFile,
 	resolveTimerTargetUnit: () => resolveTimerTargetUnit,
 	sendNotify: () => sendNotify,
@@ -295,17 +362,16 @@ function cloneUnitSection(section) {
 	return Object.freeze(Object.fromEntries(entries));
 }
 function validateServiceSection(service) {
-	for (const key of EXEC_DIRECTIVE_KEYS) assertAbsoluteExecValue(key, service[key]);
-}
-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}`);
+	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 parseStartResult(unit, output) {
+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, ``];
@@ -320,21 +386,41 @@ function parseStartResult(unit, output) {
 	};
 }
 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`;
+	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 })
+		};
+	}
 }
 function shellQuote(value) {
 	return `'${value.replaceAll(`'`, `'\\''`)}'`;
@@ -360,13 +446,33 @@ async function sendNotify(state, options) {
 	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]);
+		try {
+			await options.executor(`bash`, [`-lc`, command]);
+		} catch (cause) {
+			throw new NotifySendError(`Failed to send systemd notification through the configured executor`, {
+				args: [`-lc`, command],
+				cause,
+				command: `bash`,
+				reason: `executor-failed`,
+				stage: `executor`
+			});
+		}
 		return;
 	}
-	await execFileAsync(`systemd-notify`, args, { env: {
-		...process.env,
-		...options.socketPath === void 0 ? {} : { NOTIFY_SOCKET: options.socketPath }
-	} });
+	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 hasServiceSection(options) {
 	return `service` in options;
@@ -376,19 +482,41 @@ function hasTimerSection(options) {
 }
 function assertAbsoluteExecValue(key, value) {
 	if (isUnitValueList(value)) {
-		for (const entry of value) assertAbsoluteExecEntry(key, entry);
-		return;
+		for (const entry of value) {
+			const validation = assertAbsoluteExecEntry(key, entry);
+			if (!validation.ok) return validation;
+		}
+		return {
+			ok: true,
+			value: void 0
+		};
 	}
-	assertAbsoluteExecEntry(key, value);
+	return assertAbsoluteExecEntry(key, value);
 }
 function assertAbsoluteExecEntry(key, value) {
-	if (typeof value === `string` && value.length > 0 && !isAbsoluteExecCommand(value)) 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`);
+	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 value ? `true` : `false`;
-	return String(value);
+	if (typeof value === `boolean`) return {
+		ok: true,
+		value: value ? `true` : `false`
+	};
+	return {
+		ok: true,
+		value: String(value)
+	};
 }
 function isUnitValueList(value) {
 	return Array.isArray(value);
@@ -444,7 +572,21 @@ const notify = {
 	* sent as an additional `STATUS=...` field.
 	*/
 	async ready(options = {}) {
-		await sendNotify(`READY=1`, 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.
@@ -454,35 +596,157 @@ const notify = {
 	* `MAINPID=...`, and `options.status` is forwarded as `STATUS=...`.
 	*/
 	async watchdog(options = {}) {
-		await sendNotify(`WATCHDOG=1`, 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/systemd.ts
 /**
-* The result of installing one or more units with {@link Systemd.install}.
+* A successful systemd unit materialization.
 *
-* It records the installation directory and the on-disk path associated with
-* each installed unit.
+* It records the target directory and the on-disk path associated with each
+* materialized unit.
 */
-var SystemdInstallResult = class {
+var SystemdMaterialization = class {
 	/** The directory units were written into. */
 	directory;
-	/** The installed units together with their resolved on-disk paths. */
-	installed;
-	pathByFilename;
-	constructor(directory, installed) {
+	/** The materialized units together with their resolved on-disk paths. */
+	materialized;
+	constructor(directory, materialized) {
 		this.directory = directory;
-		this.installed = Object.freeze([...installed]);
-		this.pathByFilename = new Map(installed.map((entry) => [entry.unit.filename, entry.path]));
+		this.materialized = Object.freeze([...materialized]);
 		Object.freeze(this);
 	}
-	/** Returns the installed on-disk path for a previously installed unit. */
-	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;
-	}
 };
 /**
 * A configured interface to a specific systemd environment.
@@ -521,41 +785,50 @@ var Systemd = class {
 	* 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. When both timers and services are installed
-	* together, compile-time and runtime attachment checks ensure the timer points
-	* at one of the accompanying services.
+	* start the units on its own.
 	*/
-	async install(...units) {
-		if (units.length === 0) throw new Error(`Systemd.install() requires at least one service or timer`);
-		assertInstallableTogether(units);
-		await writeUnitDirectory(this.unitDir);
-		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 materialize(...units) {
+		return this.materializeUnits(units);
 	}
 	/**
 	* Enables one or more units via `systemctl enable`.
 	*
-	* When `linkUnits` is enabled, this first links installed unit files into the
+	* 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) throw new Error(`Systemd.enable() requires at least one service or timer`);
+		if (units.length === 0) return err(new NoUnitsProvidedError(`Systemd.enable()`));
 		const scopeArgs = this.scopeArgs();
-		await this.prepareUnits(scopeArgs, units);
-		for (const unit of units) await this.executor(`systemctl`, [
-			...scopeArgs,
-			`enable`,
-			unit.filename
-		]);
+		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
+			];
+			try {
+				await this.executor(`systemctl`, args);
+			} catch (cause) {
+				return err(new UnitEnableError(`Failed to enable ${unit.filename}`, {
+					args,
+					cause,
+					command: `systemctl`,
+					stage: `enable`,
+					unitName: unit.filename
+				}));
+			}
+		}
+		return ok(void 0);
 	}
 	/**
 	* Starts a unit and returns a parsed `systemctl show` snapshot of its final
@@ -566,19 +839,54 @@ var Systemd = class {
 	*/
 	async start(unit) {
 		const scopeArgs = this.scopeArgs();
-		await this.prepareUnits(scopeArgs, [unit]);
-		await this.executor(`systemctl`, [
+		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 status = await this.executor(`systemctl`, [
+		];
+		try {
+			await this.executor(`systemctl`, startArgs);
+		} catch (cause) {
+			return err(new UnitStartError(`Failed to start ${unit.filename}`, {
+				args: startArgs,
+				cause,
+				command: `systemctl`,
+				diagnostics: await this.collectStartDiagnostics(scopeArgs, unit.filename),
+				stage: `start`,
+				unitName: unit.filename
+			}));
+		}
+		const statusArgs = [
 			...scopeArgs,
 			`show`,
 			unit.filename,
 			`--property=Id,ActiveState,SubState,Result,ExecMainStatus`
-		]);
-		return parseStartResult(unit.filename, status.stdout);
+		];
+		let status;
+		try {
+			status = await this.executor(`systemctl`, statusArgs);
+		} catch (cause) {
+			return err(new UnitStartError(`Started ${unit.filename} but failed to query its status`, {
+				args: statusArgs,
+				cause,
+				command: `systemctl`,
+				diagnostics: await this.collectStartDiagnostics(scopeArgs, unit.filename),
+				stage: `show-status`,
+				unitName: unit.filename
+			}));
+		}
+		return ok(parseStartStatus(unit.filename, status.stdout));
 	}
 	/**
 	* Reads recent output for a managed unit.
@@ -589,10 +897,20 @@ var Systemd = class {
 	*/
 	async logs(unit, options) {
 		const fileLogPath = resolveUnitLogPath(unit);
-		if (fileLogPath !== void 0) return tailLines(await readFile(fileLogPath, `utf8`), options?.lines ?? 50);
+		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 command = [
+		const args = [`-lc`, `${[
 			`systemctl`,
 			...scopeArgs,
 			`status`,
@@ -600,27 +918,100 @@ var Systemd = class {
 			`--no-pager`,
 			`--lines`,
 			String(lines)
-		].map(shellQuote).join(` `);
-		return (await this.executor(`bash`, [`-lc`, `${command} || true`])).stdout;
+		].map(shellQuote).join(` `)} 2>&1 || true`];
+		let logs;
+		try {
+			logs = await this.executor(`bash`, args);
+		} catch (cause) {
+			return err(new UnitLogsReadError(`Failed to query logs for ${unit.filename} from systemctl status`, {
+				args,
+				cause,
+				command: `bash`,
+				reason: `status-command-failed`,
+				stage: `status`,
+				unitName: unit.filename
+			}));
+		}
+		return ok([logs.stdout, logs.stderr].filter((value) => value.length > 0).join(`\n`));
 	}
 	/** 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) {
+	async prepareUnits(scopeArgs, units, operation) {
 		if (this.linkUnits) {
 			const linkPaths = await this.collectLinkPaths(units);
-			for (const path of linkPaths) await this.executor(`systemctl`, [
-				...scopeArgs,
-				`link`,
-				path
-			]);
+			for (const path of linkPaths) {
+				const args = [
+					...scopeArgs,
+					`link`,
+					path
+				];
+				try {
+					await this.executor(`systemctl`, args);
+				} catch (cause) {
+					const linkedUnit = units.find((candidate) => this.pathFor(candidate) === path);
+					const errorContext = {
+						args,
+						cause,
+						command: `systemctl`,
+						stage: `link`,
+						...linkedUnit === void 0 ? {} : { unitName: linkedUnit.filename },
+						unitPath: path
+					};
+					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`];
+		try {
+			await this.executor(`systemctl`, args);
+		} catch (cause) {
+			throw operation === `enable` ? new UnitEnableError(`Failed to reload systemd before enable`, {
+				args,
+				cause,
+				command: `systemctl`,
+				stage: `daemon-reload`,
+				unitName: units[0]?.filename
+			}) : new UnitStartError(`Failed to reload systemd before start`, {
+				args,
+				cause,
+				command: `systemctl`,
+				stage: `daemon-reload`,
+				unitName: units[0]?.filename
+			});
 		}
-		await this.executor(`systemctl`, [...scopeArgs, `daemon-reload`]);
 	}
 	scopeArgs() {
 		return this.scope === `user` ? [`--user`] : [];
 	}
+	async collectStartDiagnostics(scopeArgs, unitName) {
+		const diagnostics = {};
+		const showCommand = [
+			`systemctl`,
+			...scopeArgs,
+			`show`,
+			unitName,
+			`--property=Id,ActiveState,SubState,Result,ExecMainStatus`
+		].map(shellQuote).join(` `);
+		const show = await this.tryBestEffortCommand(`bash`, [`-lc`, `${showCommand} 2>&1 || true`]);
+		if (show !== void 0 && show.length > 0) {
+			diagnostics.showOutput = show;
+			diagnostics.showStatus = parseStartStatus(unitName, show);
+		}
+		const statusCommand = [
+			`systemctl`,
+			...scopeArgs,
+			`status`,
+			unitName,
+			`--no-pager`,
+			`--lines`,
+			`20`
+		].map(shellQuote).join(` `);
+		const status = await this.tryBestEffortCommand(`bash`, [`-lc`, `${statusCommand} 2>&1 || true`]);
+		if (status !== void 0 && status.length > 0) diagnostics.statusOutput = status;
+		return diagnostics;
+	}
 	async collectLinkPaths(units) {
 		const paths = /* @__PURE__ */ new Set();
 		for (const unit of units) {
@@ -632,7 +1023,64 @@ var Systemd = class {
 		}
 		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)).stdout;
+		} catch {
+			return;
+		}
+	}
 };
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
 let lazyDefaultSystemd;
 /**
 * Returns the lazily created default `Systemd` instance.
@@ -659,6 +1107,10 @@ function parseFileLogPath(value) {
 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 });
 }
@@ -670,4 +1122,4 @@ async function writeUnitDirectory(path) {
 */
 const Internal = internal_exports;
 //#endregion
-export { Executable, Internal, Systemd, SystemdInstallResult, SystemdService, SystemdTimer, defaultSystemd, defineExecutable, notify };
+export { Executable, ExecutableInferenceError, Internal, InvalidExecDirectiveError, NoUnitsProvidedError, NotifySendError, Systemd, SystemdMaterialization, SystemdService, SystemdTimer, SystemdTsError, UnitEnableError, UnitLogsReadError, UnitMaterializationError, UnitStartError, defaultSystemd, defineExecutable, notify };