systemd-ts 0.3.1 → 0.3.2

package/src/main/systemctl.ts

@@ -0,0 +1,326 @@
+import { defaultCommandExecutor, parseStartStatus } from "./internal.ts";
+import { SystemctlCommandError } from "./errors.ts";
+import type { Result } from "./internal.ts";
+import type {
+  SystemctlActiveState,
+  CommandExecutor,
+  CommandOutput,
+  StartStatus,
+  SystemctlEnablementState,
+  SystemctlIsEnabledOptions,
+  SystemctlIsSystemRunningOptions,
+  SystemctlListTimersOptions,
+  SystemctlOptions,
+  SystemctlServiceStatus,
+  SystemctlStateQueryOptions,
+  SystemctlShowOptions,
+  SystemctlStatusOptions,
+  SystemctlSystemRunningState,
+  SystemctlTimerListEntry,
+} from "./types.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}.
+ */
+export class Systemctl {
+  /** Command executor used for `systemctl` subprocesses. */
+  public readonly executor: CommandExecutor;
+  /** The target manager scope, either `system` or `user`. */
+  public readonly scope: `system` | `user`;
+
+  public constructor(options: SystemctlOptions = {}) {
+    this.scope = options.scope ?? `system`;
+    this.executor = options.executor ?? defaultCommandExecutor;
+    Object.freeze(this);
+  }
+
+  /** Reloads the targeted systemd manager. */
+  public async daemonReload(): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    return this.run(`daemon-reload`);
+  }
+
+  /** Enables a unit by filename. */
+  public async enable(unit: string): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    return this.run(`enable`, unit);
+  }
+
+  /** Disables a unit by filename. */
+  public async disable(unit: string): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    return this.run(`disable`, unit);
+  }
+
+  /** Links a unit file path into the targeted manager. */
+  public async link(path: string): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    return this.run(`link`, path);
+  }
+
+  /**
+   * Checks the install-time enablement state of a unit file.
+   *
+   * Source:
+   * - systemd v260.1, `systemctl(1)`
+   */
+  public async isEnabled(
+    unit: string,
+    options: SystemctlIsEnabledOptions = {},
+  ): Promise<Result<SystemctlEnablementState, SystemctlCommandError>> {
+    const output = await this.run(
+      `is-enabled`,
+      ...(options.full ? [`--full`] : []),
+      ...(options.quiet ? [`--quiet`] : []),
+      unit,
+    );
+    if (!output.ok) {
+      return output;
+    }
+    return ok(firstNonEmptyOutputLine(output.value) as SystemctlEnablementState);
+  }
+
+  /**
+   * Checks the runtime active state of a unit.
+   *
+   * Unless `quiet` is set, this returns the state string printed by
+   * `systemctl is-active`.
+   */
+  public async isActive(
+    unit: string,
+    options: SystemctlStateQueryOptions = {},
+  ): Promise<Result<SystemctlActiveState, SystemctlCommandError>> {
+    const output = await this.run(`is-active`, ...(options.quiet ? [`--quiet`] : []), unit);
+    if (!output.ok) {
+      return output;
+    }
+    return ok(firstNonEmptyOutputLine(output.value) as SystemctlActiveState);
+  }
+
+  /**
+   * Checks whether a unit is in the failed state.
+   *
+   * Unless `quiet` is set, this returns the state string printed by
+   * `systemctl is-failed`.
+   */
+  public async isFailed(
+    unit: string,
+    options: SystemctlStateQueryOptions = {},
+  ): Promise<Result<SystemctlActiveState, SystemctlCommandError>> {
+    const output = await this.run(`is-failed`, ...(options.quiet ? [`--quiet`] : []), unit);
+    if (!output.ok) {
+      return output;
+    }
+    return ok(firstNonEmptyOutputLine(output.value) as SystemctlActiveState);
+  }
+
+  /**
+   * Queries the overall manager state reported by `systemctl is-system-running`.
+   *
+   * Source:
+   * - systemd v260.1, `systemctl(1)`
+   */
+  public async isSystemRunning(
+    options: SystemctlIsSystemRunningOptions = {},
+  ): Promise<Result<SystemctlSystemRunningState, SystemctlCommandError>> {
+    const output = await this.run(`is-system-running`, ...(options.wait ? [`--wait`] : []));
+    if (!output.ok) {
+      return output;
+    }
+    return ok(firstNonEmptyOutputLine(output.value) as SystemctlSystemRunningState);
+  }
+
+  /**
+   * Queries `systemctl show` for a unit.
+   *
+   * When `properties` are provided, only those properties are requested.
+   */
+  public async show(
+    unit: string,
+    options: SystemctlShowOptions = {},
+  ): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    const propertyFlag =
+      options.properties === undefined || 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`.
+   */
+  public async showProperties(
+    unit: string,
+    options: SystemctlShowOptions = {},
+  ): Promise<Result<Readonly<Record<string, string>>, SystemctlCommandError>> {
+    const output = await this.show(unit, options);
+    if (!output.ok) {
+      return output;
+    }
+    return ok(parseSystemctlShowOutput(output.value.stdout));
+  }
+
+  /**
+   * Queries the standard status-related `show` properties for a unit and
+   * returns a parsed snapshot.
+   */
+  public async showStatus(unit: string): Promise<Result<StartStatus, SystemctlCommandError>> {
+    return this.showServiceStatus(unit);
+  }
+
+  /**
+   * Queries the standard service-status `show` properties for a service unit
+   * and returns a parsed snapshot.
+   */
+  public async showServiceStatus(
+    unit: string,
+  ): Promise<Result<SystemctlServiceStatus, SystemctlCommandError>> {
+    const output = await this.show(unit, {
+      properties: [`Id`, `ActiveState`, `SubState`, `Result`, `ExecMainStatus`],
+    });
+    if (!output.ok) {
+      return output;
+    }
+    return ok(parseStartStatus(unit, output.value.stdout));
+  }
+
+  /**
+   * Queries `systemctl list-timers` and returns the observed JSON payload
+   * shape directly, with raw integer timestamps left intact.
+   */
+  public async listTimers(
+    options: SystemctlListTimersOptions = {},
+  ): Promise<Result<readonly SystemctlTimerListEntry[], SystemctlCommandError>> {
+    const args = [
+      `list-timers`,
+      ...(options.all ? [`--all`] : []),
+      ...((options.noPager ?? true) ? [`--no-pager`] : []),
+      `--output=json`,
+      ...(options.patterns ?? []),
+    ] as const;
+    const output = await this.run(...args);
+    if (!output.ok) {
+      return output;
+    }
+    try {
+      return ok(JSON.parse(output.value.stdout) as readonly SystemctlTimerListEntry[]);
+    } catch (cause) {
+      return err(
+        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. */
+  public async start(unit: string): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    return this.run(`start`, unit);
+  }
+
+  /** Stops a unit by filename. */
+  public async stop(unit: string): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    return this.run(`stop`, unit);
+  }
+
+  /** Restarts a unit by filename. */
+  public async restart(unit: string): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    return this.run(`restart`, unit);
+  }
+
+  /**
+   * Resets the failed state for matching units, or for all units when no
+   * patterns are provided.
+   */
+  public async resetFailed(
+    patterns: readonly string[] = [],
+  ): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    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.
+   */
+  public async status(
+    unit: string,
+    options: SystemctlStatusOptions = {},
+  ): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    const args = [`status`, unit] as string[];
+    if (options.noPager ?? true) {
+      args.push(`--no-pager`);
+    }
+    if (options.lines !== undefined) {
+      args.push(`--lines`, String(options.lines));
+    }
+
+    return this.run(...args);
+  }
+
+  /** Executes a raw `systemctl` invocation with scope-aware arguments. */
+  public async run(
+    ...args: readonly string[]
+  ): Promise<Result<CommandOutput, SystemctlCommandError>> {
+    const scopedArgs = [...this.scopeArgs(), ...args];
+    try {
+      return ok(await this.executor(`systemctl`, scopedArgs));
+    } catch (cause) {
+      return err(
+        new SystemctlCommandError(`Failed to run systemctl ${args[0] ?? `command`}`, {
+          args: scopedArgs,
+          cause,
+          command: `systemctl`,
+          operation: args[0],
+          reason: `executor-failed`,
+        }),
+      );
+    }
+  }
+
+  private scopeArgs(): readonly string[] {
+    return this.scope === `user` ? [`--user`] : [];
+  }
+}
+
+function ok<TValue>(value: TValue): Result<TValue, never> {
+  return { ok: true, value };
+}
+
+function err<TError>(error: TError): Result<never, TError> {
+  return { ok: false, error };
+}
+
+function parseSystemctlShowOutput(output: string): Readonly<Record<string, string>> {
+  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, ``] as const;
+          }
+
+          return [line.slice(0, separatorIndex), line.slice(separatorIndex + 1)] as const;
+        }),
+    ),
+  );
+}
+
+function firstNonEmptyOutputLine(output: CommandOutput): string {
+  const line = [output.stdout, output.stderr]
+    .flatMap((value) => value.split(`\n`))
+    .map((value) => value.trim())
+    .find((value) => value.length > 0);
+  return line ?? ``;
+}

package/src/main/systemd-service.ts

@@ -0,0 +1,80 @@
+import {
+  cloneUnitSection,
+  freezeUnitOptions,
+  normalizeUnitName,
+  renderUnitFile,
+  validateServiceSection,
+} from "./internal.ts";
+import type { ExecutableInferenceError, InvalidExecDirectiveError } from "./errors.ts";
+import type { Result } from "./internal.ts";
+import type {
+  ExactSystemdServiceOptions,
+  ServiceBaseName,
+  ServiceFilename,
+  SystemdServiceOptions,
+} from "./types.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
+ */
+export class SystemdService<const TOptions extends SystemdServiceOptions = SystemdServiceOptions> {
+  /** Optional `[Install]` section for enable-time relationships. */
+  public readonly install: TOptions[`install`] | undefined;
+  /** The normalized base unit name, without the `.service` suffix. */
+  public readonly name: ServiceBaseName<TOptions[`name`]>;
+  /** The fully frozen original options used to construct this service. */
+  public readonly options: Readonly<TOptions>;
+  /** The `[Service]` section payload. */
+  public readonly service: TOptions[`service`];
+  /** Optional `[Unit]` section metadata and dependency configuration. */
+  public readonly unit: TOptions[`unit`] | undefined;
+
+  /**
+   * 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.
+   */
+  public constructor(options: TOptions & ExactSystemdServiceOptions<TOptions>) {
+    this.options = freezeUnitOptions(options as unknown as TOptions);
+    this.name = normalizeUnitName(options.name, `.service`) as ServiceBaseName<TOptions[`name`]>;
+    this.unit = cloneUnitSection(options.unit) as TOptions[`unit`] | undefined;
+    this.service = (cloneUnitSection(options.service) ?? {}) as TOptions[`service`];
+    this.install = cloneUnitSection(options.install) as TOptions[`install`] | undefined;
+    Object.freeze(this);
+  }
+
+  /** The canonical unit filename, including the `.service` suffix. */
+  public get filename(): ServiceFilename<TOptions[`name`]> {
+    return `${this.name}.service` as ServiceFilename<TOptions[`name`]>;
+  }
+
+  /**
+   * 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.
+   */
+  public render(): Result<string, ExecutableInferenceError | InvalidExecDirectiveError> {
+    const validation = validateServiceSection(this.service);
+    if (!validation.ok) {
+      return validation;
+    }
+
+    return renderUnitFile([
+      [`Unit`, this.unit],
+      [`Service`, this.service],
+      [`Install`, this.install],
+    ]);
+  }
+}

package/src/main/systemd-timer.ts

@@ -0,0 +1,80 @@
+import {
+  cloneUnitSection,
+  freezeUnitOptions,
+  normalizeUnitName,
+  renderUnitFile,
+  resolveTimerTargetUnit,
+} from "./internal.ts";
+import type { ExecutableInferenceError } from "./errors.ts";
+import type { Result } from "./internal.ts";
+import type {
+  ExactSystemdTimerOptions,
+  SystemdTimerOptions,
+  TimerBaseName,
+  TimerFilename,
+  TimerTargetServiceName,
+  TimerTargetUnit,
+} from "./types.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
+ */
+export class SystemdTimer<const TOptions extends SystemdTimerOptions = SystemdTimerOptions> {
+  /** Optional `[Install]` section for enable-time relationships. */
+  public readonly install: TOptions[`install`] | undefined;
+  /** The normalized base unit name, without the `.timer` suffix. */
+  public readonly name: TimerBaseName<TOptions[`name`]>;
+  /** The fully frozen original options used to construct this timer. */
+  public readonly options: Readonly<TOptions>;
+  /** The attached service basename inferred from `targetUnit`. */
+  public readonly targetServiceName: TimerTargetServiceName<TOptions>;
+  /** The unit name this timer activates, explicit or implicit. */
+  public readonly targetUnit: TimerTargetUnit<TOptions>;
+  /** The `[Timer]` section payload. */
+  public readonly timer: TOptions[`timer`];
+  /** Optional `[Unit]` section metadata and dependency configuration. */
+  public readonly unit: TOptions[`unit`] | undefined;
+
+  /**
+   * 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.
+   */
+  public constructor(options: TOptions & ExactSystemdTimerOptions<TOptions>) {
+    this.options = freezeUnitOptions(options as unknown as TOptions);
+    this.name = normalizeUnitName(options.name, `.timer`) as TimerBaseName<TOptions[`name`]>;
+    this.unit = cloneUnitSection(options.unit) as TOptions[`unit`] | undefined;
+    this.timer = (cloneUnitSection(options.timer) ?? {}) as TOptions[`timer`];
+    this.install = cloneUnitSection(options.install) as TOptions[`install`] | undefined;
+    this.targetUnit = resolveTimerTargetUnit(
+      options as unknown as TOptions,
+    ) as TimerTargetUnit<TOptions>;
+    this.targetServiceName = normalizeUnitName(
+      this.targetUnit,
+      `.service`,
+    ) as TimerTargetServiceName<TOptions>;
+    Object.freeze(this);
+  }
+
+  /** The canonical unit filename, including the `.timer` suffix. */
+  public get filename(): TimerFilename<TOptions[`name`]> {
+    return `${this.name}.timer` as TimerFilename<TOptions[`name`]>;
+  }
+
+  /** Renders the timer as a complete unit file. */
+  public render(): Result<string, ExecutableInferenceError> {
+    return renderUnitFile([
+      [`Unit`, this.unit],
+      [`Timer`, this.timer],
+      [`Install`, this.install],
+    ]);
+  }
+}