systemd-ts 0.1.1 → 0.3.0

package/dist/index.d.mts

@@ -1,3 +1,96 @@
+declare namespace internal_d_exports {
+  export { Result, cloneUnitSection, defaultCommandExecutor, defaultUnitDirForScope, extractCommandOutput, fileExists, freezeUnitOptions, normalizeUnitName, parseStartStatus, renderUnitFile, resolveTimerTargetUnit, sendNotify, validateServiceSection };
+}
+type Result<TValue, TError> = {
+  readonly ok: true;
+  readonly value: TValue;
+} | {
+  readonly ok: false;
+  readonly error: TError;
+};
+type SectionLike = object;
+declare function normalizeUnitName(name: string, suffix: `.service` | `.timer`): string;
+declare function resolveTimerTargetUnit(options: SystemdTimerOptions): string;
+declare function defaultUnitDirForScope(scope: `system` | `user`): string;
+declare function freezeUnitOptions<TOptions extends SystemdServiceOptions | SystemdTimerOptions>(options: TOptions): Readonly<TOptions>;
+declare function cloneUnitSection<TSection extends SectionLike | undefined>(section: TSection): TSection;
+declare function validateServiceSection(service: SystemdServiceSection): Result<void, InvalidExecDirectiveError>;
+declare function parseStartStatus(unit: string, output: string): StartStatus;
+declare function renderUnitFile(sections: ReadonlyArray<readonly [string, SectionLike | undefined]>): Result<string, ExecutableInferenceError>;
+declare function defaultCommandExecutor(command: string, args: readonly string[], options?: CommandExecutionOptions): Promise<CommandOutput>;
+declare function fileExists(path: string): Promise<boolean>;
+declare function sendNotify(state: `READY=1` | `WATCHDOG=1`, options: NotifyOptions): Promise<void>;
+declare function extractCommandOutput(cause: unknown): CommandOutput | undefined;
+//#endregion
+//#region src/main/executable.d.ts
+/**
+ * An immutable description of a runnable module entrypoint that can be used in
+ * executable-valued systemd unit directives.
+ *
+ * `Executable` captures three pieces of information:
+ * - the absolute runtime binary that should launch the module
+ * - the absolute path to the module itself
+ * - any additional arguments that should be passed after the module path
+ *
+ * Most consumers will create one via {@link defineExecutable} and then pass it
+ * into a {@link SystemdService} directive such as `ExecStart`, `ExecStop`, or
+ * `ExecReload`.
+ */
+declare class Executable {
+  /** Additional arguments passed after the module path. */
+  readonly args: readonly string[];
+  /** Inference issue captured when no explicit module path was provided. */
+  readonly inferenceError: ExecutableInferenceError | undefined;
+  /** Absolute path to the module that should be executed. */
+  readonly modulePath: string;
+  /** Absolute path to the runtime binary that should launch the module. */
+  readonly runtimeEntrypoint: string;
+  /**
+   * Creates an executable description.
+   *
+   * When `modulePath` is omitted, the calling module is inferred from the
+   * current stack so `defineExecutable()` can be used inline from the module
+   * that should become runnable.
+   *
+   * When `runtimeEntrypoint` is omitted, the current process executable is
+   * used. This works well for the common case where the same runtime that is
+   * evaluating your module should also be used by systemd.
+   */
+  constructor(options?: ExecutableOptions);
+  /**
+   * Returns the executable as raw command parts.
+   *
+   * The first element is always the runtime entrypoint, followed by the module
+   * path and any configured arguments.
+   */
+  toCommandParts(): Result<readonly [string, ...string[]], ExecutableInferenceError>;
+  /**
+   * Renders the executable as a shell-quoted command string suitable for
+   * executable-valued systemd directives such as `ExecStart=`.
+   */
+  toExecStart(): Result<string, ExecutableInferenceError>;
+}
+/**
+ * Defines a module as a runnable executable and returns its immutable
+ * `Executable` description.
+ *
+ * This helper is designed for the pattern:
+ *
+ * ```ts
+ * export default defineExecutable(async () => {
+ *   // do work here
+ * });
+ * ```
+ *
+ * When the defining module is executed as the main entrypoint, `fn` is invoked.
+ * When the module is merely imported, `fn` is not run and only the executable
+ * description is returned.
+ *
+ * Pass `options.runtimeEntrypoint` to override the default runtime binary when
+ * the current process is not the exact runtime you want systemd to use.
+ */
+declare function defineExecutable(fn: () => void | Promise<void>, options?: ExecutableOptions): Executable;
+//#endregion
 //#region src/main/systemd-service.d.ts
 /**
  * An immutable definition of a `.service` unit.
@@ -38,7 +131,7 @@ declare class SystemdService<const TOptions extends SystemdServiceOptions = Syst
    * and `ExecStop`, ensuring they use absolute runtime entrypoints as required
    * by systemd.
    */
-  render(): string;
+  render(): Result<string, ExecutableInferenceError | InvalidExecDirectiveError>;
 }
 //#endregion
 //#region src/main/systemd-timer.d.ts
@@ -77,7 +170,7 @@ declare class SystemdTimer<const TOptions extends SystemdTimerOptions = SystemdT
   /** The canonical unit filename, including the `.timer` suffix. */
   get filename(): TimerFilename<TOptions[`name`]>;
   /** Renders the timer as a complete unit file. */
-  render(): string;
+  render(): Result<string, ExecutableInferenceError>;
 }
 //#endregion
 //#region src/main/types.d.ts
@@ -963,14 +1056,6 @@ interface SystemdServiceSection extends CustomDirectiveSection {
   /** Takes a directory path relative to the service's root directory specified by RootDirectory=, or the special value ~. Sets the working directory for executed processes. If set to ~, the home directory of the user specified in User= is used. If not set, defaults to the root directory when systemd is running as a system instance and the respective user's home directory if run as user. If the setting is prefixed with the - character, a missing working directory is not considered fatal. If RootDirectory=/RootImage= is not set, then WorkingDirectory= is relative to the root of the system running the service manager. Note that setting this parameter might result in additional dependencies to be added to the unit (see above). Source: systemd v260.1, `systemd.exec(5)`. */
   readonly WorkingDirectory?: string;
 }
-/**
- * @deprecated Use one of the specific section interfaces instead:
- * `SystemdUnitSection`, `SystemdInstallSection`, `SystemdServiceSection`, or
- * `SystemdTimerSection`.
- */
-interface UnitSection {
-  readonly [key: string]: UnitSectionValue;
-}
 interface SystemdServiceOptions {
   readonly install?: SystemdInstallSection;
   readonly name: string;
@@ -1001,27 +1086,81 @@ interface SystemdOptions {
   readonly scope?: `system` | `user`;
   readonly unitDir?: string;
 }
-interface CommandResult {
+interface SystemctlOptions {
+  readonly executor?: CommandExecutor;
+  readonly scope?: `system` | `user`;
+}
+type SystemctlEnablementState = `enabled` | `enabled-runtime` | `linked` | `linked-runtime` | `alias` | `masked` | `masked-runtime` | `static` | `indirect` | `disabled` | `generated` | `transient` | `bad` | `not-found` | (string & {});
+type SystemctlActiveState = `active` | `reloading` | `inactive` | `failed` | `activating` | `deactivating` | `maintenance` | `refreshing`;
+interface CommandOutput {
   readonly stderr: string;
   readonly stdout: string;
 }
-type CommandExecutor = (command: string, args: readonly string[]) => Promise<CommandResult>;
+interface CommandExecutionOptions {
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+type CommandExecutor = (command: string, args: readonly string[], options?: CommandExecutionOptions) => Promise<CommandOutput>;
 interface LogsOptions {
   readonly lines?: number;
 }
+interface SystemctlShowOptions {
+  readonly properties?: readonly string[];
+}
+interface SystemctlStatusOptions {
+  readonly lines?: number;
+  readonly noPager?: boolean;
+}
+interface SystemctlListTimersOptions {
+  readonly all?: boolean;
+  readonly noPager?: boolean;
+  readonly patterns?: readonly string[];
+}
+/**
+ * The official `systemctl list-timers --output=json` entry shape exposed by
+ * this library.
+ *
+ * Timestamp fields are returned as raw integer values exactly as reported by
+ * `systemctl`, so callers can compose their own normalization strategy.
+ */
+interface SystemctlTimerListEntry {
+  readonly next: number;
+  readonly left: number;
+  readonly last: number;
+  readonly passed: number;
+  readonly unit: `${string}.timer`;
+  readonly activates: string;
+}
+interface SystemctlIsEnabledOptions {
+  readonly full?: boolean;
+  readonly quiet?: boolean;
+}
+interface SystemctlStateQueryOptions {
+  readonly quiet?: boolean;
+}
+interface SystemctlIsSystemRunningOptions {
+  readonly wait?: boolean;
+}
+type SystemctlSystemRunningState = `initializing` | `starting` | `running` | `degraded` | `maintenance` | `stopping` | `offline` | `unknown`;
 interface NotifyOptions {
   readonly executor?: CommandExecutor;
   readonly pid?: number;
   readonly socketPath?: string;
   readonly status?: string;
 }
-interface StartResult {
+interface StartStatus {
   readonly activeState: string;
   readonly execMainStatus: number | undefined;
   readonly result: string;
   readonly subState: string;
   readonly unit: string;
 }
+/**
+ * The typed `systemctl show` status projection exposed for service units.
+ *
+ * This currently mirrors the shared start/status snapshot shape used by the
+ * library's service workflows.
+ */
+interface SystemctlServiceStatus extends StartStatus {}
 interface ExecutableOptions {
   readonly args?: readonly string[];
   readonly modulePath?: string;
@@ -1040,7 +1179,7 @@ type IsWideString<Value extends string> = string extends Value ? true : false;
 type AnySystemdService = SystemdService<SystemdServiceOptions>;
 type AnySystemdTimer = SystemdTimer<SystemdTimerOptions>;
 type SystemdUnit = AnySystemdService | AnySystemdTimer;
-interface InstalledUnit<TUnit extends SystemdUnit = SystemdUnit> {
+interface MaterializedUnit<TUnit extends SystemdUnit = SystemdUnit> {
   readonly path: string;
   readonly unit: TUnit;
 }
@@ -1051,72 +1190,132 @@ type HasServices<TUnits extends readonly SystemdUnit[]> = [ServiceNamesIn<TUnits
 type HasMismatchedServiceTimerPairs<TUnits extends readonly SystemdUnit[]> = HasServices<TUnits> extends true ? [MismatchedTimers<TUnits>] extends [never] ? false : true : false;
 type ValidInstallUnits<TUnits extends readonly SystemdUnit[]> = HasMismatchedServiceTimerPairs<TUnits> extends true ? never : TUnits;
 //#endregion
-//#region src/main/executable.d.ts
-/**
- * An immutable description of a runnable module entrypoint that can be used in
- * executable-valued systemd unit directives.
- *
- * `Executable` captures three pieces of information:
- * - the absolute runtime binary that should launch the module
- * - the absolute path to the module itself
- * - any additional arguments that should be passed after the module path
- *
- * Most consumers will create one via {@link defineExecutable} and then pass it
- * into a {@link SystemdService} directive such as `ExecStart`, `ExecStop`, or
- * `ExecReload`.
- */
-declare class Executable {
-  /** Additional arguments passed after the module path. */
-  readonly args: readonly string[];
-  /** Absolute path to the module that should be executed. */
-  readonly modulePath: string;
-  /** Absolute path to the runtime binary that should launch the module. */
-  readonly runtimeEntrypoint: string;
-  /**
-   * Creates an executable description.
-   *
-   * When `modulePath` is omitted, the calling module is inferred from the
-   * current stack so `defineExecutable()` can be used inline from the module
-   * that should become runnable.
-   *
-   * When `runtimeEntrypoint` is omitted, the current process executable is
-   * used. This works well for the common case where the same runtime that is
-   * evaluating your module should also be used by systemd.
-   */
-  constructor(options?: ExecutableOptions);
-  /**
-   * Returns the executable as raw command parts.
-   *
-   * The first element is always the runtime entrypoint, followed by the module
-   * path and any configured arguments.
-   */
-  toCommandParts(): readonly [string, ...string[]];
-  /**
-   * Renders the executable as a shell-quoted command string suitable for
-   * executable-valued systemd directives such as `ExecStart=`.
-   */
-  toExecStart(): string;
+//#region src/main/errors.d.ts
+type SystemdTsErrorCode = `SYSTEMD_TS_INVALID_EXEC_DIRECTIVE` | `SYSTEMD_TS_NO_UNITS_PROVIDED` | `SYSTEMD_TS_EXECUTABLE_INFERENCE` | `SYSTEMD_TS_UNIT_MATERIALIZATION` | `SYSTEMD_TS_UNIT_ENABLE` | `SYSTEMD_TS_UNIT_START` | `SYSTEMD_TS_UNIT_LOGS` | `SYSTEMD_TS_SYSTEMCTL` | `SYSTEMD_TS_NOTIFY_SEND`;
+interface SystemdTsErrorOptions {
+  readonly cause?: unknown;
+}
+interface SystemdCommandErrorOptions extends SystemdTsErrorOptions {
+  readonly args?: readonly string[];
+  readonly command?: string;
+  readonly environmentReason?: SystemdCommandEnvironmentReason;
+  readonly stage?: string;
+  readonly unitName?: string;
+  readonly unitPath?: string;
+}
+interface UnitStartDiagnostics {
+  readonly showOutput?: string;
+  readonly showStatus?: StartStatus;
+  readonly statusOutput?: string;
+}
+interface UnitStartErrorOptions extends SystemdCommandErrorOptions {
+  readonly diagnostics?: UnitStartDiagnostics;
+}
+interface UnitMaterializationErrorOptions extends SystemdTsErrorOptions {
+  readonly reason?: UnitMaterializationErrorReason;
+  readonly operation?: `create-directory` | `write-file`;
+  readonly unitName?: string;
+  readonly unitPath?: string;
+}
+type UnitMaterializationErrorReason = `file-system-failed` | `invalid-unit-directory` | `permission-denied`;
+interface UnitLogsReadErrorOptions extends SystemdCommandErrorOptions {
+  readonly reason?: UnitLogsReadErrorReason;
+  readonly unitPath?: string;
+}
+type UnitLogsReadErrorReason = `missing-log-file` | `log-file-read-failed` | `status-command-failed`;
+interface NotifySendErrorOptions extends SystemdCommandErrorOptions {
+  readonly reason?: NotifySendErrorReason;
+}
+type NotifySendErrorReason = `executor-failed` | `systemd-notify-failed`;
+interface SystemctlCommandErrorOptions extends SystemdCommandErrorOptions {
+  readonly operation?: string;
+  readonly reason?: SystemctlCommandErrorReason;
+}
+type SystemctlCommandErrorReason = `executor-failed` | `invalid-json`;
+type SystemdCommandEnvironmentReason = `manager-unavailable` | `missing-command` | `permission-denied`;
+declare class SystemdTsError extends Error {
+  readonly code: SystemdTsErrorCode;
+  constructor(code: SystemdTsErrorCode, message: string, options?: SystemdTsErrorOptions);
+}
+declare class InvalidExecDirectiveError extends SystemdTsError {
+  readonly directive: string;
+  constructor(directive: string, options?: SystemdTsErrorOptions);
+}
+declare class NoUnitsProvidedError extends SystemdTsError {
+  readonly operation: string;
+  constructor(operation: string, options?: SystemdTsErrorOptions);
+}
+declare class ExecutableInferenceError extends SystemdTsError {
+  constructor(options?: SystemdTsErrorOptions);
+}
+declare class UnitMaterializationError extends SystemdTsError {
+  readonly operation: `create-directory` | `write-file` | undefined;
+  readonly reason: UnitMaterializationErrorReason | undefined;
+  readonly unitName: string | undefined;
+  readonly unitPath: string | undefined;
+  constructor(message: string, options?: UnitMaterializationErrorOptions);
+}
+declare class UnitEnableError extends SystemdTsError {
+  readonly args: readonly string[] | undefined;
+  readonly command: string | undefined;
+  readonly environmentReason: SystemdCommandEnvironmentReason | undefined;
+  readonly exitCode: number | undefined;
+  readonly stage: string | undefined;
+  readonly stderr: string | undefined;
+  readonly stdout: string | undefined;
+  readonly unitName: string | undefined;
+  readonly unitPath: string | undefined;
+  constructor(message: string, options?: SystemdCommandErrorOptions);
+}
+declare class UnitStartError extends SystemdTsError {
+  readonly args: readonly string[] | undefined;
+  readonly command: string | undefined;
+  readonly diagnostics: UnitStartDiagnostics | undefined;
+  readonly environmentReason: SystemdCommandEnvironmentReason | undefined;
+  readonly exitCode: number | undefined;
+  readonly stage: string | undefined;
+  readonly stderr: string | undefined;
+  readonly stdout: string | undefined;
+  readonly unitName: string | undefined;
+  readonly unitPath: string | undefined;
+  constructor(message: string, options?: UnitStartErrorOptions);
+}
+declare class UnitLogsReadError extends SystemdTsError {
+  readonly args: readonly string[] | undefined;
+  readonly command: string | undefined;
+  readonly environmentReason: SystemdCommandEnvironmentReason | undefined;
+  readonly exitCode: number | undefined;
+  readonly reason: UnitLogsReadErrorReason | undefined;
+  readonly stage: string | undefined;
+  readonly stderr: string | undefined;
+  readonly stdout: string | undefined;
+  readonly unitName: string | undefined;
+  readonly unitPath: string | undefined;
+  constructor(message: string, options?: UnitLogsReadErrorOptions);
+}
+declare class NotifySendError extends SystemdTsError {
+  readonly args: readonly string[] | undefined;
+  readonly command: string | undefined;
+  readonly environmentReason: SystemdCommandEnvironmentReason | undefined;
+  readonly exitCode: number | undefined;
+  readonly reason: NotifySendErrorReason | undefined;
+  readonly stage: string | undefined;
+  readonly stderr: string | undefined;
+  readonly stdout: string | undefined;
+  constructor(message: string, options?: NotifySendErrorOptions);
+}
+declare class SystemctlCommandError extends SystemdTsError {
+  readonly args: readonly string[] | undefined;
+  readonly command: string | undefined;
+  readonly environmentReason: SystemdCommandEnvironmentReason | undefined;
+  readonly exitCode: number | undefined;
+  readonly operation: string | undefined;
+  readonly reason: SystemctlCommandErrorReason | undefined;
+  readonly stage: string | undefined;
+  readonly stderr: string | undefined;
+  readonly stdout: string | undefined;
+  constructor(message: string, options?: SystemctlCommandErrorOptions);
 }
-/**
- * Defines a module as a runnable executable and returns its immutable
- * `Executable` description.
- *
- * This helper is designed for the pattern:
- *
- * ```ts
- * export default defineExecutable(async () => {
- *   // do work here
- * });
- * ```
- *
- * When the defining module is executed as the main entrypoint, `fn` is invoked.
- * When the module is merely imported, `fn` is not run and only the executable
- * description is returned.
- *
- * Pass `options.runtimeEntrypoint` to override the default runtime binary when
- * the current process is not the exact runtime you want systemd to use.
- */
-declare function defineExecutable(fn: () => void | Promise<void>, options?: ExecutableOptions): Executable;
 //#endregion
 //#region src/main/notify.d.ts
 /**
@@ -1139,7 +1338,7 @@ declare const notify: {
    * ready to be considered fully started. If `options.status` is provided, it is
    * sent as an additional `STATUS=...` field.
    */
-  ready(options?: NotifyOptions): Promise<void>;
+  ready(options?: NotifyOptions): Promise<Result<void, NotifySendError>>;
   /**
    * Sends `WATCHDOG=1` to systemd.
    *
@@ -1147,25 +1346,153 @@ declare const notify: {
    * watchdog heartbeat. If `options.pid` is provided, it is sent as
    * `MAINPID=...`, and `options.status` is forwarded as `STATUS=...`.
    */
-  watchdog(options?: NotifyOptions): Promise<void>;
+  watchdog(options?: NotifyOptions): Promise<Result<void, NotifySendError>>;
 };
 //#endregion
+//#region src/main/systemctl.d.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}.
+ */
+declare class Systemctl {
+  /** Command executor used for `systemctl` subprocesses. */
+  readonly executor: CommandExecutor;
+  /** The target manager scope, either `system` or `user`. */
+  readonly scope: `system` | `user`;
+  constructor(options?: SystemctlOptions);
+  /** Reloads the targeted systemd manager. */
+  daemonReload(): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  /** Enables a unit by filename. */
+  enable(unit: string): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  /** Disables a unit by filename. */
+  disable(unit: string): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  /** Links a unit file path into the targeted manager. */
+  link(path: string): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  /**
+   * Checks the install-time enablement state of a unit file.
+   *
+   * Source:
+   * - systemd v260.1, `systemctl(1)`
+   */
+  isEnabled(unit: string, options?: SystemctlIsEnabledOptions): Promise<Result<SystemctlEnablementState, SystemctlCommandError>>;
+  /**
+   * Checks the runtime active state of a unit.
+   *
+   * Unless `quiet` is set, this returns the state string printed by
+   * `systemctl is-active`.
+   */
+  isActive(unit: string, options?: SystemctlStateQueryOptions): Promise<Result<SystemctlActiveState, SystemctlCommandError>>;
+  /**
+   * Checks whether a unit is in the failed state.
+   *
+   * Unless `quiet` is set, this returns the state string printed by
+   * `systemctl is-failed`.
+   */
+  isFailed(unit: string, options?: SystemctlStateQueryOptions): Promise<Result<SystemctlActiveState, SystemctlCommandError>>;
+  /**
+   * Queries the overall manager state reported by `systemctl is-system-running`.
+   *
+   * Source:
+   * - systemd v260.1, `systemctl(1)`
+   */
+  isSystemRunning(options?: SystemctlIsSystemRunningOptions): Promise<Result<SystemctlSystemRunningState, SystemctlCommandError>>;
+  /**
+   * Queries `systemctl show` for a unit.
+   *
+   * When `properties` are provided, only those properties are requested.
+   */
+  show(unit: string, options?: SystemctlShowOptions): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  /**
+   * Queries `systemctl show` and parses the result into a key-value object.
+   *
+   * Properties are returned exactly as printed by `systemctl show`.
+   */
+  showProperties(unit: string, options?: SystemctlShowOptions): Promise<Result<Readonly<Record<string, string>>, SystemctlCommandError>>;
+  /**
+   * Queries the standard status-related `show` properties for a unit and
+   * returns a parsed snapshot.
+   */
+  showStatus(unit: string): Promise<Result<StartStatus, SystemctlCommandError>>;
+  /**
+   * Queries the standard service-status `show` properties for a service unit
+   * and returns a parsed snapshot.
+   */
+  showServiceStatus(unit: string): Promise<Result<SystemctlServiceStatus, SystemctlCommandError>>;
+  /**
+   * Queries `systemctl list-timers` and returns the observed JSON payload
+   * shape directly, with raw integer timestamps left intact.
+   */
+  listTimers(options?: SystemctlListTimersOptions): Promise<Result<readonly SystemctlTimerListEntry[], SystemctlCommandError>>;
+  /** Starts a unit by filename. */
+  start(unit: string): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  /** Stops a unit by filename. */
+  stop(unit: string): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  /** Restarts a unit by filename. */
+  restart(unit: string): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  /**
+   * Resets the failed state for matching units, or for all units when no
+   * patterns are provided.
+   */
+  resetFailed(patterns?: readonly string[]): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  /**
+   * Queries `systemctl status` for a unit.
+   *
+   * This is primarily a human-oriented command and is best paired with
+   * `show()` when structured state is needed.
+   */
+  status(unit: string, options?: SystemctlStatusOptions): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  /** Executes a raw `systemctl` invocation with scope-aware arguments. */
+  run(...args: readonly string[]): Promise<Result<CommandOutput, SystemctlCommandError>>;
+  private scopeArgs;
+}
+//#endregion
 //#region src/main/systemd.d.ts
+interface SystemdTsAttachOptions {
+  readonly owner: string;
+  readonly enable?: boolean;
+  readonly start?: boolean;
+}
+interface SystemdTsDetachOptions {
+  readonly deleteUnitFiles?: boolean;
+  readonly disable?: boolean;
+  readonly stop?: boolean;
+}
+interface SystemdTsReattachOptions extends SystemdTsAttachOptions {
+  readonly disableRemoved?: boolean;
+  readonly prune?: boolean;
+  readonly restartUpdated?: boolean;
+  readonly stopRemoved?: boolean;
+}
+interface SystemdTsAttachmentSelector {
+  readonly owner: string;
+}
+interface SystemdTsAttachmentResult {
+  readonly added: readonly string[];
+  readonly directory: string;
+  readonly enabled: readonly string[];
+  readonly manifestPath: string;
+  readonly owner: string;
+  readonly removed: readonly string[];
+  readonly restarted: readonly string[];
+  readonly started: readonly string[];
+  readonly unchanged: readonly string[];
+  readonly updated: readonly string[];
+}
 /**
- * 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.
  */
-declare class SystemdInstallResult<TUnits extends readonly SystemdUnit[] = readonly SystemdUnit[]> {
+declare class SystemdMaterialization<TUnits extends readonly SystemdUnit[] = readonly SystemdUnit[]> {
   /** The directory units were written into. */
   readonly directory: string;
-  /** The installed units together with their resolved on-disk paths. */
-  readonly installed: readonly InstalledUnit<TUnits[number]>[];
-  private readonly pathByFilename;
-  constructor(directory: string, installed: readonly InstalledUnit<TUnits[number]>[]);
-  /** Returns the installed on-disk path for a previously installed unit. */
-  pathFor(unit: TUnits[number]): string;
+  /** The materialized units together with their resolved on-disk paths. */
+  readonly materialized: readonly MaterializedUnit<TUnits[number]>[];
+  constructor(directory: string, materialized: readonly MaterializedUnit<TUnits[number]>[]);
 }
 /**
  * A configured interface to a specific systemd environment.
@@ -1184,6 +1511,10 @@ declare class Systemd {
   readonly linkUnits: boolean;
   /** The target manager scope, either `system` or `user`. */
   readonly scope: `system` | `user`;
+  /** The low-level `systemctl` client for this configured target. */
+  readonly systemctl: Systemctl;
+  /** Higher-level `systemd-ts` upkeep helpers for application-owned units. */
+  readonly ts: SystemdTs;
   /** The directory used when materializing unit files. */
   readonly unitDir: string;
   /**
@@ -1198,19 +1529,17 @@ declare class Systemd {
    * 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.
    */
-  install<const TUnits extends readonly SystemdUnit[]>(...units: TUnits & ValidInstallUnits<TUnits>): Promise<SystemdInstallResult<TUnits>>;
+  materialize<const TUnits extends readonly SystemdUnit[]>(...units: TUnits & ValidInstallUnits<TUnits>): Promise<Result<SystemdMaterialization<TUnits>, ExecutableInferenceError | InvalidExecDirectiveError | NoUnitsProvidedError | UnitMaterializationError>>;
   /**
    * 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.
    */
-  enable(...units: readonly SystemdUnit[]): Promise<void>;
+  enable(...units: readonly SystemdUnit[]): Promise<Result<void, NoUnitsProvidedError | UnitEnableError>>;
   /**
    * Starts a unit and returns a parsed `systemctl show` snapshot of its final
    * observed state.
@@ -1218,7 +1547,7 @@ declare class Systemd {
    * For oneshot services, a successful result commonly means `ActiveState` is
    * already back to `inactive` by the time the status snapshot is collected.
    */
-  start(unit: SystemdUnit): Promise<StartResult>;
+  start(unit: SystemdUnit): Promise<Result<StartStatus, UnitStartError>>;
   /**
    * Reads recent output for a managed unit.
    *
@@ -1226,12 +1555,44 @@ declare class Systemd {
    * `StandardError`, this reads directly from that file. Otherwise it falls back
    * to `systemctl status --lines ...`.
    */
-  logs(unit: SystemdUnit, options?: LogsOptions): Promise<string>;
+  logs(unit: SystemdUnit, options?: LogsOptions): Promise<Result<string, UnitLogsReadError>>;
   /** Returns the on-disk unit-file path this instance uses for the given unit. */
   pathFor(unit: SystemdUnit): string;
   private prepareUnits;
   private scopeArgs;
+  private collectStartDiagnostics;
   private collectLinkPaths;
+  private materializeUnits;
+  private tryBestEffortCommand;
+}
+/**
+ * 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.
+ */
+declare class SystemdTs {
+  private readonly systemd;
+  constructor(systemd: Systemd);
+  attach(units: readonly SystemdUnit[], options: SystemdTsAttachOptions): Promise<Result<SystemdTsAttachmentResult, ExecutableInferenceError | InvalidExecDirectiveError | NoUnitsProvidedError | UnitEnableError | UnitMaterializationError | UnitStartError>>;
+  detach(selector: SystemdTsAttachmentSelector, options?: SystemdTsDetachOptions): Promise<Result<{
+    readonly deleted: readonly string[];
+    readonly detached: readonly string[];
+    readonly disabled: readonly string[];
+    readonly owner: string;
+    readonly stopped: readonly string[];
+  }, Error>>;
+  reattach(units: readonly SystemdUnit[], options: SystemdTsReattachOptions): Promise<Result<SystemdTsAttachmentResult, ExecutableInferenceError | InvalidExecDirectiveError | NoUnitsProvidedError | UnitEnableError | UnitMaterializationError | UnitStartError | Error>>;
+  private describeUnits;
+  private diffManifest;
+  private manifestDir;
+  private manifestPathFor;
+  private readManifest;
+  private runSystemctl;
+  private removeManagedUnitPath;
+  private scopeArgs;
+  private writeManifest;
 }
 /**
  * Returns the lazily created default `Systemd` instance.
@@ -1240,23 +1601,6 @@ declare class Systemd {
  * command execution.
  */
 declare function defaultSystemd(): Systemd;
-declare namespace internal_d_exports {
-  export { assertInstallableTogether, cloneUnitSection, defaultCommandExecutor, defaultUnitDirForScope, fileExists, freezeUnitOptions, normalizeUnitName, parseStartResult, renderUnitFile, resolveTimerTargetUnit, sendNotify, shellQuote, validateServiceSection };
-}
-type SectionLike = object;
-declare function normalizeUnitName(name: string, suffix: `.service` | `.timer`): string;
-declare function resolveTimerTargetUnit(options: SystemdTimerOptions): string;
-declare function defaultUnitDirForScope(scope: `system` | `user`): string;
-declare function freezeUnitOptions<TOptions extends SystemdServiceOptions | SystemdTimerOptions>(options: TOptions): Readonly<TOptions>;
-declare function cloneUnitSection<TSection extends SectionLike | undefined>(section: TSection): TSection;
-declare function validateServiceSection(service: SystemdServiceSection): void;
-declare function assertInstallableTogether(units: readonly SystemdUnit[]): void;
-declare function parseStartResult(unit: string, output: string): StartResult;
-declare function renderUnitFile(sections: ReadonlyArray<readonly [string, SectionLike | undefined]>): string;
-declare function shellQuote(value: string): string;
-declare function defaultCommandExecutor(command: string, args: readonly string[]): Promise<CommandResult>;
-declare function fileExists(path: string): Promise<boolean>;
-declare function sendNotify(state: `READY=1` | `WATCHDOG=1`, options: NotifyOptions): Promise<void>;
 //#endregion
 //#region src/main/index.d.ts
 /**
@@ -1265,4 +1609,4 @@ declare function sendNotify(state: `READY=1` | `WATCHDOG=1`, options: NotifyOpti
  */
 declare const Internal: typeof internal_d_exports;
 //#endregion
-export { type AnySystemdService, type AnySystemdTimer, type CommandExecutor, type CommandResult, Executable, type ExecutableOptions, type InstalledUnit, Internal, type LogsOptions, type NotifyOptions, type ServiceBaseName, type ServiceFilename, type StartResult, Systemd, SystemdInstallResult, type SystemdOptions, SystemdService, type SystemdServiceOptions, SystemdTimer, type SystemdTimerOptions, type SystemdUnit, type TimerBaseName, type TimerFilename, type TimerTargetServiceName, type TimerTargetUnit, type UnitSection, type UnitValue, type ValidInstallUnits, defaultSystemd, defineExecutable, notify };
+export { type AnySystemdService, type AnySystemdTimer, type CommandExecutionOptions, type CommandExecutor, type CommandOutput, Executable, ExecutableInferenceError, type ExecutableOptions, Internal, InvalidExecDirectiveError, type LogsOptions, type MaterializedUnit, NoUnitsProvidedError, type NotifyOptions, NotifySendError, type NotifySendErrorReason, type Result, type ServiceBaseName, type ServiceFilename, type StartStatus, Systemctl, type SystemctlActiveState, SystemctlCommandError, type SystemctlCommandErrorReason, type SystemctlEnablementState, type SystemctlIsEnabledOptions, type SystemctlIsSystemRunningOptions, type SystemctlListTimersOptions, type SystemctlOptions, type SystemctlServiceStatus, type SystemctlShowOptions, type SystemctlStateQueryOptions, type SystemctlStatusOptions, type SystemctlSystemRunningState, type SystemctlTimerListEntry, Systemd, type SystemdCommandEnvironmentReason, SystemdMaterialization, type SystemdOptions, SystemdService, type SystemdServiceOptions, SystemdTimer, type SystemdTimerOptions, SystemdTs, type SystemdTsAttachOptions, type SystemdTsAttachmentResult, type SystemdTsAttachmentSelector, type SystemdTsDetachOptions, SystemdTsError, type SystemdTsReattachOptions, type SystemdUnit, type TimerBaseName, type TimerFilename, type TimerTargetServiceName, type TimerTargetUnit, UnitEnableError, UnitLogsReadError, type UnitLogsReadErrorReason, UnitMaterializationError, type UnitMaterializationErrorReason, UnitStartError, type UnitValue, type ValidInstallUnits, defaultSystemd, defineExecutable, notify };