systemd-ts 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -2,7 +2,7 @@ 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
@@ -144,6 +144,30 @@ var NotifySendError = class extends SystemdTsError {
 		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;
@@ -245,7 +269,7 @@ var Executable = class {
 		if (!commandParts.ok) return commandParts;
 		return {
 			ok: true,
-			value: commandParts.value.map(shellQuote$1).join(` `)
+			value: commandParts.value.map(shellQuote).join(` `)
 		};
 	}
 };
@@ -295,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) {
@@ -311,6 +335,7 @@ var internal_exports = /* @__PURE__ */ __exportAll({
 	cloneUnitSection: () => cloneUnitSection,
 	defaultCommandExecutor: () => defaultCommandExecutor,
 	defaultUnitDirForScope: () => defaultUnitDirForScope,
+	extractCommandOutput: () => extractCommandOutput,
 	fileExists: () => fileExists,
 	freezeUnitOptions: () => freezeUnitOptions,
 	normalizeUnitName: () => normalizeUnitName,
@@ -318,7 +343,6 @@ var internal_exports = /* @__PURE__ */ __exportAll({
 	renderUnitFile: () => renderUnitFile,
 	resolveTimerTargetUnit: () => resolveTimerTargetUnit,
 	sendNotify: () => sendNotify,
-	shellQuote: () => shellQuote,
 	validateServiceSection: () => validateServiceSection
 });
 const EXEC_DIRECTIVE_KEYS = [
@@ -422,11 +446,11 @@ function renderUnitFile(sections) {
 		};
 	}
 }
-function shellQuote(value) {
-	return `'${value.replaceAll(`'`, `'\\''`)}'`;
-}
-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
@@ -441,18 +465,17 @@ 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);
 		try {
-			await options.executor(`bash`, [`-lc`, command]);
+			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: [`-lc`, command],
+				args,
 				cause,
-				command: `bash`,
+				command: `systemd-notify`,
 				reason: `executor-failed`,
 				stage: `executor`
 			});
@@ -474,6 +497,17 @@ async function sendNotify(state, options) {
 		});
 	}
 }
+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;
 }
@@ -546,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
 /**
@@ -730,6 +761,224 @@ var SystemdTimer = class {
 	}
 };
 //#endregion
+//#region src/main/systemctl.ts
+/**
+* A TypeScript-first client for invoking `systemctl` with structured argument
+* vectors instead of shell-composed command strings.
+*
+* This lower-level primitive is useful both on its own and as the subprocess
+* transport underneath higher-level abstractions such as {@link Systemd}.
+*/
+var Systemctl = class {
+	/** Command executor used for `systemctl` subprocesses. */
+	executor;
+	/** The target manager scope, either `system` or `user`. */
+	scope;
+	constructor(options = {}) {
+		this.scope = options.scope ?? `system`;
+		this.executor = options.executor ?? defaultCommandExecutor;
+		Object.freeze(this);
+	}
+	/** Reloads the targeted systemd manager. */
+	async daemonReload() {
+		return this.run(`daemon-reload`);
+	}
+	/** Enables a unit by filename. */
+	async enable(unit) {
+		return this.run(`enable`, unit);
+	}
+	/** Disables a unit by filename. */
+	async disable(unit) {
+		return this.run(`disable`, unit);
+	}
+	/** Links a unit file path into the targeted manager. */
+	async link(path) {
+		return this.run(`link`, path);
+	}
+	/**
+	* Checks the install-time enablement state of a unit file.
+	*
+	* Source:
+	* - systemd v260.1, `systemctl(1)`
+	*/
+	async isEnabled(unit, options = {}) {
+		const output = await this.run(`is-enabled`, ...options.full ? [`--full`] : [], ...options.quiet ? [`--quiet`] : [], unit);
+		if (!output.ok) return output;
+		return ok$1(firstNonEmptyOutputLine(output.value));
+	}
+	/**
+	* Checks the runtime active state of a unit.
+	*
+	* Unless `quiet` is set, this returns the state string printed by
+	* `systemctl is-active`.
+	*/
+	async isActive(unit, options = {}) {
+		const output = await this.run(`is-active`, ...options.quiet ? [`--quiet`] : [], unit);
+		if (!output.ok) return output;
+		return ok$1(firstNonEmptyOutputLine(output.value));
+	}
+	/**
+	* Checks whether a unit is in the failed state.
+	*
+	* Unless `quiet` is set, this returns the state string printed by
+	* `systemctl is-failed`.
+	*/
+	async isFailed(unit, options = {}) {
+		const output = await this.run(`is-failed`, ...options.quiet ? [`--quiet`] : [], unit);
+		if (!output.ok) return output;
+		return ok$1(firstNonEmptyOutputLine(output.value));
+	}
+	/**
+	* Queries the overall manager state reported by `systemctl is-system-running`.
+	*
+	* Source:
+	* - systemd v260.1, `systemctl(1)`
+	*/
+	async isSystemRunning(options = {}) {
+		const output = await this.run(`is-system-running`, ...options.wait ? [`--wait`] : []);
+		if (!output.ok) return output;
+		return ok$1(firstNonEmptyOutputLine(output.value));
+	}
+	/**
+	* Queries `systemctl show` for a unit.
+	*
+	* When `properties` are provided, only those properties are requested.
+	*/
+	async show(unit, options = {}) {
+		const propertyFlag = options.properties === void 0 || options.properties.length === 0 ? [] : [`--property=${options.properties.join(`,`)}`];
+		return this.run(`show`, unit, ...propertyFlag);
+	}
+	/**
+	* Queries `systemctl show` and parses the result into a key-value object.
+	*
+	* Properties are returned exactly as printed by `systemctl show`.
+	*/
+	async showProperties(unit, options = {}) {
+		const output = await this.show(unit, options);
+		if (!output.ok) return output;
+		return ok$1(parseSystemctlShowOutput(output.value.stdout));
+	}
+	/**
+	* Queries the standard status-related `show` properties for a unit and
+	* returns a parsed snapshot.
+	*/
+	async showStatus(unit) {
+		return this.showServiceStatus(unit);
+	}
+	/**
+	* Queries the standard service-status `show` properties for a service unit
+	* and returns a parsed snapshot.
+	*/
+	async showServiceStatus(unit) {
+		const output = await this.show(unit, { properties: [
+			`Id`,
+			`ActiveState`,
+			`SubState`,
+			`Result`,
+			`ExecMainStatus`
+		] });
+		if (!output.ok) return output;
+		return ok$1(parseStartStatus(unit, output.value.stdout));
+	}
+	/**
+	* Queries `systemctl list-timers` and returns the observed JSON payload
+	* shape directly, with raw integer timestamps left intact.
+	*/
+	async listTimers(options = {}) {
+		const args = [
+			`list-timers`,
+			...options.all ? [`--all`] : [],
+			...options.noPager ?? true ? [`--no-pager`] : [],
+			`--output=json`,
+			...options.patterns ?? []
+		];
+		const output = await this.run(...args);
+		if (!output.ok) return output;
+		try {
+			return ok$1(JSON.parse(output.value.stdout));
+		} catch (cause) {
+			return err$1(new SystemctlCommandError(`Failed to parse JSON output from systemctl list-timers`, {
+				args: [...this.scopeArgs(), ...args],
+				cause,
+				command: `systemctl`,
+				operation: `list-timers`,
+				reason: `invalid-json`
+			}));
+		}
+	}
+	/** Starts a unit by filename. */
+	async start(unit) {
+		return this.run(`start`, unit);
+	}
+	/** Stops a unit by filename. */
+	async stop(unit) {
+		return this.run(`stop`, unit);
+	}
+	/** Restarts a unit by filename. */
+	async restart(unit) {
+		return this.run(`restart`, unit);
+	}
+	/**
+	* Resets the failed state for matching units, or for all units when no
+	* patterns are provided.
+	*/
+	async resetFailed(patterns = []) {
+		return this.run(`reset-failed`, ...patterns);
+	}
+	/**
+	* Queries `systemctl status` for a unit.
+	*
+	* This is primarily a human-oriented command and is best paired with
+	* `show()` when structured state is needed.
+	*/
+	async status(unit, options = {}) {
+		const args = [`status`, unit];
+		if (options.noPager ?? true) args.push(`--no-pager`);
+		if (options.lines !== void 0) args.push(`--lines`, String(options.lines));
+		return this.run(...args);
+	}
+	/** Executes a raw `systemctl` invocation with scope-aware arguments. */
+	async run(...args) {
+		const scopedArgs = [...this.scopeArgs(), ...args];
+		try {
+			return ok$1(await this.executor(`systemctl`, scopedArgs));
+		} catch (cause) {
+			return err$1(new SystemctlCommandError(`Failed to run systemctl ${args[0] ?? `command`}`, {
+				args: scopedArgs,
+				cause,
+				command: `systemctl`,
+				operation: args[0],
+				reason: `executor-failed`
+			}));
+		}
+	}
+	scopeArgs() {
+		return this.scope === `user` ? [`--user`] : [];
+	}
+};
+function ok$1(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err$1(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+function parseSystemctlShowOutput(output) {
+	return Object.freeze(Object.fromEntries(output.split(`\n`).map((line) => line.trim()).filter((line) => line.length > 0).map((line) => {
+		const separatorIndex = line.indexOf(`=`);
+		if (separatorIndex === -1) return [line, ``];
+		return [line.slice(0, separatorIndex), line.slice(separatorIndex + 1)];
+	})));
+}
+function firstNonEmptyOutputLine(output) {
+	return [output.stdout, output.stderr].flatMap((value) => value.split(`\n`)).map((value) => value.trim()).find((value) => value.length > 0) ?? ``;
+}
+//#endregion
 //#region src/main/systemd.ts
 /**
 * A successful systemd unit materialization.
@@ -765,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;
 	/**
@@ -779,6 +1032,11 @@ 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);
 	}
 	/**
@@ -816,16 +1074,17 @@ var Systemd = class {
 				`enable`,
 				unit.filename
 			];
-			try {
-				await this.executor(`systemctl`, args);
-			} catch (cause) {
-				return err(new UnitEnableError(`Failed to enable ${unit.filename}`, {
+			const enabled = await this.systemctl.enable(unit.filename);
+			if (!enabled.ok) {
+				const errorOptions = {
 					args,
-					cause,
+					cause: enabled.error,
 					command: `systemctl`,
 					stage: `enable`,
-					unitName: unit.filename
-				}));
+					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);
@@ -855,38 +1114,38 @@ var Systemd = class {
 			`start`,
 			unit.filename
 		];
-		try {
-			await this.executor(`systemctl`, startArgs);
-		} catch (cause) {
-			return err(new UnitStartError(`Failed to start ${unit.filename}`, {
+		const started = await this.systemctl.start(unit.filename);
+		if (!started.ok) {
+			const errorOptions = {
 				args: startArgs,
-				cause,
+				cause: started.error,
 				command: `systemctl`,
 				diagnostics: await this.collectStartDiagnostics(scopeArgs, unit.filename),
 				stage: `start`,
-				unitName: unit.filename
-			}));
+				unitName: unit.filename,
+				...started.error.environmentReason === void 0 ? {} : { environmentReason: started.error.environmentReason }
+			};
+			return err(new UnitStartError(`Failed to start ${unit.filename}`, errorOptions));
 		}
-		const statusArgs = [
-			...scopeArgs,
-			`show`,
-			unit.filename,
-			`--property=Id,ActiveState,SubState,Result,ExecMainStatus`
-		];
-		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,
+		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
-			}));
+				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(parseStartStatus(unit.filename, status.stdout));
+		return ok(status.value);
 	}
 	/**
 	* Reads recent output for a managed unit.
@@ -910,29 +1169,26 @@ var Systemd = class {
 		}
 		const scopeArgs = this.scopeArgs();
 		const lines = options?.lines ?? 50;
-		const args = [`-lc`, `${[
-			`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(` `)} 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`));
+		];
+		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) {
@@ -947,39 +1203,34 @@ var Systemd = class {
 					`link`,
 					path
 				];
-				try {
-					await this.executor(`systemctl`, args);
-				} catch (cause) {
+				const linked = await this.systemctl.link(path);
+				if (!linked.ok) {
 					const linkedUnit = units.find((candidate) => this.pathFor(candidate) === path);
 					const errorContext = {
 						args,
-						cause,
+						cause: linked.error,
 						command: `systemctl`,
 						stage: `link`,
-						...linkedUnit === void 0 ? {} : { unitName: linkedUnit.filename },
-						unitPath: path
+						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`];
-		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`, {
+		const reloaded = await this.systemctl.daemonReload();
+		if (!reloaded.ok) {
+			const errorContext = {
 				args,
-				cause,
+				cause: reloaded.error,
 				command: `systemctl`,
 				stage: `daemon-reload`,
-				unitName: units[0]?.filename
-			});
+				...reloaded.error.environmentReason === void 0 ? {} : { environmentReason: reloaded.error.environmentReason },
+				...units[0]?.filename === void 0 ? {} : { unitName: units[0].filename }
+			};
+			throw operation === `enable` ? new UnitEnableError(`Failed to reload systemd before enable`, errorContext) : new UnitStartError(`Failed to reload systemd before start`, errorContext);
 		}
 	}
 	scopeArgs() {
@@ -987,29 +1238,31 @@ var Systemd = class {
 	}
 	async collectStartDiagnostics(scopeArgs, unitName) {
 		const diagnostics = {};
-		const showCommand = [
-			`systemctl`,
+		const showArgs = [
 			...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 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 statusCommand = [
-			`systemctl`,
+		const statusArgs = [
 			...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;
+		];
+		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) {
@@ -1063,11 +1316,240 @@ var Systemd = class {
 	}
 	async tryBestEffortCommand(command, args) {
 		try {
-			return (await this.executor(command, args)).stdout;
+			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 {
@@ -1081,6 +1563,9 @@ function err(error) {
 		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.
@@ -1122,4 +1607,4 @@ async function writeUnitDirectory(path) {
 */
 const Internal = internal_exports;
 //#endregion
-export { Executable, ExecutableInferenceError, Internal, InvalidExecDirectiveError, NoUnitsProvidedError, NotifySendError, Systemd, SystemdMaterialization, SystemdService, SystemdTimer, SystemdTsError, UnitEnableError, UnitLogsReadError, UnitMaterializationError, UnitStartError, 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 };