systemd-ts 0.2.0 → 0.3.0

package/README.md

@@ -1,63 +1,312 @@
 # systemd-ts
 
-`systemd-ts` is a library for declaring, rendering, and managing `systemd`
-services and timers from TypeScript.
+`systemd-ts` lets you work with `systemd` from TypeScript.
 
-## Usage
+It is designed around a few practical jobs:
 
-The example below materializes a user-scoped service and timer for a small
-nightly backup job. The service does the work, the timer schedules it, and
-`Systemd` writes both unit files before enabling and starting the timer.
+- keep application-owned units defined in `.timer` and `.service`up to date from TypeScript
+- use `systemctl` from TypeScript
+- define a service from TypeScript
+- define a service that runs on a timer from TypeScript
+- keep the code that runs the job close to the code that defines the service and timer
+
+The library has two layers:
+
+- `systemd.ts.*` is the code-owned upkeep layer for attaching, reattaching, and
+  detaching application-managed units.
+- `systemd.*` stays close to raw `systemd` concepts like materializing units and
+  starting them directly.
+
+That lets the README start from the application code story without giving up a
+lower-level `systemd` surface when you want it.
+
+It is also a good place to learn `systemd` itself. The unit directives are
+deeply typed, documented in the TypeScript surface, and maintained against
+versioned upstream manpage material, so the library doubles as a guided way to
+explore what `systemd` can do without starting from loose strings and scattered
+shell examples.
+
+## What It Can Do
+
+### Keep application-owned units up to date
+
+If your application owns a service or timer and wants to keep that unit set up
+to date across reinstalls, updates, or reconfiguration, use `systemd.ts`.
 
 ```ts
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import backupJob from "./backup-job.ts";
 import { Systemd, SystemdService, SystemdTimer } from "systemd-ts";
 
-const userUnitDir = join(homedir(), ".config/systemd/user");
+const systemd = new Systemd({
+  scope: `user`,
+  unitDir: join(homedir(), `.config/systemd/user`),
+  linkUnits: true,
+});
 
 const service = new SystemdService({
-  name: "backup-db",
+  name: `backup-db`,
+  service: {
+    Type: `oneshot`,
+    ExecStart: backupJob,
+  },
+});
+
+const timer = new SystemdTimer({
+  name: `backup-db`,
+  timer: {
+    OnCalendar: `daily`,
+    Persistent: true,
+    Unit: service.filename,
+  },
+  install: {
+    WantedBy: `timers.target`,
+  },
+});
+
+const attached = await systemd.ts.reattach([service, timer], {
+  owner: `com.example.backup-db`,
+  enable: true,
+  start: true,
+  prune: true,
+});
+if (!attached.ok) {
+  throw attached.error;
+}
+```
+
+This is the highest-level upkeep workflow in the library. It is designed for
+desktop apps, self-updating agents, OTA-managed software, and other code-owned
+service setups where the application itself is responsible for the unit set it
+maintains.
+
+### Use `systemctl` from TypeScript
+
+If you want a typed, argv-first `systemctl` client, use `Systemctl`.
+
+```ts
+import { Systemctl } from "systemd-ts";
+
+const systemctl = new Systemctl({ scope: `user` });
+
+const timers = await systemctl.listTimers({ all: true });
+if (!timers.ok) {
+  throw timers.error;
+}
+
+const status = await systemctl.showServiceStatus(`backup-db.service`);
+if (!status.ok) {
+  throw status.error;
+}
+
+console.log(timers.value);
+console.log(status.value);
+```
+
+This is a good fit when you already know the units you want to inspect or
+control and you want to stay inside TypeScript instead of shelling out from app
+code by hand.
+
+### Define a service from TypeScript
+
+If you want to describe a service unit in code, use `SystemdService`.
+
+```ts
+import { SystemdService } from "systemd-ts";
+
+const service = new SystemdService({
+  name: `backup-db`,
   unit: {
-    Description: "Write a nightly database backup",
+    Description: `Write a database backup`,
   },
   service: {
-    Type: "oneshot",
-    ExecStart: "/usr/bin/bash -lc '/srv/app/bin/backup-db >> /srv/app/log/backup-db.log 2>&1'",
+    Type: `oneshot`,
+    ExecStart: `/srv/app/bin/backup-db`,
+    StandardOutput: `append:/srv/app/log/backup-db.log`,
+    StandardError: `append:/srv/app/log/backup-db.log`,
+  },
+});
+```
+
+That service can be rendered into a real unit file, materialized into a unit
+directory, and then managed through `Systemd` or `Systemctl`.
+
+### Define a service that runs on a timer
+
+If you want a scheduled job, pair `SystemdService` with `SystemdTimer`.
+
+```ts
+import { SystemdService, SystemdTimer } from "systemd-ts";
+
+const service = new SystemdService({
+  name: `backup-db`,
+  service: {
+    Type: `oneshot`,
+    ExecStart: `/srv/app/bin/backup-db`,
   },
 });
 
 const timer = new SystemdTimer({
-  name: "backup-db",
+  name: `backup-db`,
   unit: {
-    Description: "Run the database backup every night",
+    Description: `Run the backup every night`,
+  },
+  timer: {
+    OnCalendar: `03:15`,
+    Persistent: true,
+    Unit: service.filename,
+  },
+  install: {
+    WantedBy: `timers.target`,
+  },
+});
+```
+
+This gives you a real `.service` plus a real `.timer`, both defined from the
+same TypeScript module.
+
+### Keep the executable close to the unit definitions
+
+For many projects, the nicest workflow is to colocate the job entrypoint with
+the service and timer that run it.
+
+`defineExecutable()` is designed for that pattern:
+
+```ts
+import { defineExecutable } from "systemd-ts";
+
+export default defineExecutable(async () => {
+  console.log(`Writing backup...`);
+});
+```
+
+Then you can use that executable directly in a service definition:
+
+```ts
+import backupJob from "./backup-job.ts";
+import { SystemdService, SystemdTimer } from "systemd-ts";
+
+const service = new SystemdService({
+  name: `backup-db`,
+  service: {
+    Type: `oneshot`,
+    ExecStart: backupJob,
   },
+});
+
+const timer = new SystemdTimer({
+  name: `backup-db`,
   timer: {
-    OnCalendar: "03:15",
+    OnCalendar: `daily`,
+    Unit: service.filename,
+  },
+  install: {
+    WantedBy: `timers.target`,
+  },
+});
+```
+
+That keeps the scheduled code, the service definition, and the timer definition
+near each other instead of scattering them across shell scripts and unit files.
+
+## A Typical Flow
+
+Most applications use the library in a flow like this:
+
+1. Define a `SystemdService`
+2. Optionally define a matching `SystemdTimer`
+3. Reattach the desired unit set through `systemd.ts`
+4. Inspect or control units directly through `Systemctl` or `Systemd` when needed
+
+```ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import backupJob from "./backup-job.ts";
+import { Systemd, SystemdService, SystemdTimer } from "systemd-ts";
+
+const systemd = new Systemd({
+  scope: `user`,
+  unitDir: join(homedir(), `.config/systemd/user`),
+  linkUnits: true,
+});
+
+const service = new SystemdService({
+  name: `backup-db`,
+  service: {
+    Type: `oneshot`,
+    ExecStart: backupJob,
+  },
+});
+
+const timer = new SystemdTimer({
+  name: `backup-db`,
+  timer: {
+    OnCalendar: `daily`,
     Persistent: true,
     Unit: service.filename,
   },
   install: {
-    WantedBy: "timers.target",
+    WantedBy: `timers.target`,
   },
 });
 
+const reattached = await systemd.ts.reattach([service, timer], {
+  owner: `com.example.backup-db`,
+  enable: true,
+  start: true,
+  prune: true,
+});
+if (!reattached.ok) {
+  throw reattached.error;
+}
+```
+
+### Using The `Systemd` API Directly
+
+If you want to stay closer to raw `systemd` operations, use the lower-level
+`Systemd` methods directly:
+
+```ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import backupJob from "./backup-job.ts";
+import { Systemd, SystemdService, SystemdTimer } from "systemd-ts";
+
 const systemd = new Systemd({
-  scope: "user",
-  unitDir: userUnitDir,
+  scope: `user`,
+  unitDir: join(homedir(), `.config/systemd/user`),
   linkUnits: true,
 });
 
+const service = new SystemdService({
+  name: `backup-db`,
+  service: {
+    Type: `oneshot`,
+    ExecStart: backupJob,
+  },
+});
+
+const timer = new SystemdTimer({
+  name: `backup-db`,
+  timer: {
+    OnCalendar: `daily`,
+    Persistent: true,
+    Unit: service.filename,
+  },
+  install: {
+    WantedBy: `timers.target`,
+  },
+});
+
 const materialized = await systemd.materialize(service, timer);
 if (!materialized.ok) {
   throw materialized.error;
 }
 
-console.log(systemd.pathFor(service));
-console.log(systemd.pathFor(timer));
-console.log(materialized.value.materialized);
-
 const enabled = await systemd.enable(timer);
 if (!enabled.ok) {
   throw enabled.error;
@@ -69,6 +318,18 @@ if (!started.ok) {
 }
 ```
 
-That will materialize `backup-db.service` and `backup-db.timer` into the user's
-unit directory, enable the timer under `timers.target`, and ask `systemd --user`
-to start waiting for the first scheduled run.
+This lower-level flow is useful when you want exact control over
+materialization, enablement, or startup behavior without going through the
+code-owned upkeep layer.
+
+## Explore Further
+
+The README is meant to answer what the library is for.
+
+If you want the exact method surface, result types, or lower-level details, the
+next places to look are:
+
+- `Systemctl` for direct `systemctl` usage from TypeScript
+- `Systemd` for materialization plus unit lifecycle workflows
+- `SystemdService` and `SystemdTimer` for unit definitions
+- `Executable` and `defineExecutable()` for colocated runnable entrypoints

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 declare namespace internal_d_exports {
-  export { Result, cloneUnitSection, defaultCommandExecutor, defaultUnitDirForScope, fileExists, freezeUnitOptions, normalizeUnitName, parseStartStatus, renderUnitFile, resolveTimerTargetUnit, sendNotify, shellQuote, validateServiceSection };
+  export { Result, cloneUnitSection, defaultCommandExecutor, defaultUnitDirForScope, extractCommandOutput, fileExists, freezeUnitOptions, normalizeUnitName, parseStartStatus, renderUnitFile, resolveTimerTargetUnit, sendNotify, validateServiceSection };
 }
 type Result<TValue, TError> = {
   readonly ok: true;
@@ -17,10 +17,10 @@ declare function cloneUnitSection<TSection extends SectionLike | undefined>(sect
 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 shellQuote(value: string): string;
-declare function defaultCommandExecutor(command: string, args: readonly string[]): Promise<CommandOutput>;
+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
 /**
@@ -1086,14 +1086,61 @@ interface SystemdOptions {
   readonly scope?: `system` | `user`;
   readonly unitDir?: string;
 }
+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<CommandOutput>;
+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;
@@ -1107,6 +1154,13 @@ interface StartStatus {
   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;
@@ -1137,7 +1191,7 @@ type HasMismatchedServiceTimerPairs<TUnits extends readonly SystemdUnit[]> = Has
 type ValidInstallUnits<TUnits extends readonly SystemdUnit[]> = HasMismatchedServiceTimerPairs<TUnits> extends true ? never : TUnits;
 //#endregion
 //#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_NOTIFY_SEND`;
+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;
 }
@@ -1173,6 +1227,11 @@ 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;
@@ -1245,6 +1304,18 @@ declare class NotifySendError extends SystemdTsError {
   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);
+}
 //#endregion
 //#region src/main/notify.d.ts
 /**
@@ -1278,7 +1349,138 @@ declare const notify: {
   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[];
+}
 /**
  * A successful systemd unit materialization.
  *
@@ -1309,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;
   /**
@@ -1359,6 +1565,35 @@ declare class Systemd {
   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.
  *
@@ -1374,4 +1609,4 @@ declare function defaultSystemd(): Systemd;
  */
 declare const Internal: typeof internal_d_exports;
 //#endregion
-export { type AnySystemdService, type AnySystemdTimer, 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, Systemd, type SystemdCommandEnvironmentReason, SystemdMaterialization, type SystemdOptions, SystemdService, type SystemdServiceOptions, SystemdTimer, type SystemdTimerOptions, SystemdTsError, 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 };
+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 };