systemd-ts 0.1.1 → 0.3.0

package/dist/index.mjs

@@ -2,9 +2,201 @@ 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, writeFile } from "node:fs/promises";
+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);
 /**
@@ -23,6 +215,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 +234,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 +247,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).join(` `)
+		};
 	}
 };
 /**
@@ -86,20 +294,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);
@@ -112,7 +319,7 @@ function isMainModule(modulePath) {
 	if (mainArg === void 0) return false;
 	return normalizeFilePath(mainArg) === normalizeFilePath(modulePath);
 }
-function shellQuote$1(value) {
+function shellQuote(value) {
 	return `'${value.replaceAll(`'`, `'\\''`)}'`;
 }
 function normalizeFilePath(path) {
@@ -123,135 +330,19 @@ 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,
+	extractCommandOutput: () => extractCommandOutput,
 	fileExists: () => fileExists,
 	freezeUnitOptions: () => freezeUnitOptions,
 	normalizeUnitName: () => normalizeUnitName,
-	parseStartResult: () => parseStartResult,
+	parseStartStatus: () => parseStartStatus,
 	renderUnitFile: () => renderUnitFile,
 	resolveTimerTargetUnit: () => resolveTimerTargetUnit,
 	sendNotify: () => sendNotify,
-	shellQuote: () => shellQuote,
 	validateServiceSection: () => validateServiceSection
 });
 const EXEC_DIRECTIVE_KEYS = [
@@ -295,17 +386,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,27 +410,47 @@ 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`;
-}
-function shellQuote(value) {
-	return `'${value.replaceAll(`'`, `'\\''`)}'`;
+	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) {
-	const result = await execFileAsync(command, [...args]);
+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
@@ -355,18 +465,48 @@ async function fileExists(path) {
 	}
 }
 async function sendNotify(state, options) {
-	const args = [state];
+	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) {
-		const command = buildNotifyShellCommand(args, options.socketPath);
-		await options.executor(`bash`, [`-lc`, command]);
+		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;
 	}
-	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 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;
@@ -376,19 +516,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);
@@ -418,9 +580,6 @@ function isAbsoluteExecCommand(value) {
 	}
 	return value[index] === `/`;
 }
-function buildNotifyShellCommand(args, socketPath) {
-	return `${socketPath === void 0 ? `` : `NOTIFY_SOCKET=${shellQuote(socketPath)} `}${[`systemd-notify`, ...args].map(shellQuote).join(` `)}`;
-}
 //#endregion
 //#region src/main/notify.ts
 /**
@@ -444,7 +603,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 +627,375 @@ 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/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
 /**
-* 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.
@@ -501,6 +1014,10 @@ var Systemd = class {
 	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;
 	/**
@@ -515,47 +1032,62 @@ var Systemd = class {
 		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. 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
+			];
+			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
@@ -566,19 +1098,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`, [
-			...scopeArgs,
-			`show`,
-			unit.filename,
-			`--property=Id,ActiveState,SubState,Result,ExecMainStatus`
-		]);
-		return parseStartResult(unit.filename, status.stdout);
+		];
+		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.
@@ -589,38 +1156,115 @@ 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 = [
-			`systemctl`,
+		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)
-		].map(shellQuote).join(` `);
-		return (await this.executor(`bash`, [`-lc`, `${command} || true`])).stdout;
+		];
+		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) {
+	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
+				];
+				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);
 		}
-		await this.executor(`systemctl`, [...scopeArgs, `daemon-reload`]);
 	}
 	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) {
@@ -632,7 +1276,296 @@ 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);
+		} 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.
@@ -659,6 +1592,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 +1607,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, Systemctl, SystemctlCommandError, Systemd, SystemdMaterialization, SystemdService, SystemdTimer, SystemdTs, SystemdTsError, UnitEnableError, UnitLogsReadError, UnitMaterializationError, UnitStartError, defaultSystemd, defineExecutable, notify };