systemd-ts 0.0.0 → 0.1.0

package/dist/index.d.mts

@@ -1,19 +1,580 @@
-//#region src/index.d.ts
+//#region src/main/systemd-service.d.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
+ */
+declare class SystemdService<const TOptions extends SystemdServiceOptions = SystemdServiceOptions> {
+  /** Optional `[Install]` section for enable-time relationships. */
+  readonly install: TOptions[`install`] | undefined;
+  /** The normalized base unit name, without the `.service` suffix. */
+  readonly name: ServiceBaseName<TOptions[`name`]>;
+  /** The fully frozen original options used to construct this service. */
+  readonly options: Readonly<TOptions>;
+  /** The `[Service]` section payload. */
+  readonly service: TOptions[`service`];
+  /** Optional `[Unit]` section metadata and dependency configuration. */
+  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.
+   */
+  constructor(options: TOptions & ExactSystemdServiceOptions<TOptions>);
+  /** The canonical unit filename, including the `.service` suffix. */
+  get filename(): 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.
+   */
+  render(): string;
+}
+//#endregion
+//#region src/main/systemd-timer.d.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
+ */
+declare class SystemdTimer<const TOptions extends SystemdTimerOptions = SystemdTimerOptions> {
+  /** Optional `[Install]` section for enable-time relationships. */
+  readonly install: TOptions[`install`] | undefined;
+  /** The normalized base unit name, without the `.timer` suffix. */
+  readonly name: TimerBaseName<TOptions[`name`]>;
+  /** The fully frozen original options used to construct this timer. */
+  readonly options: Readonly<TOptions>;
+  /** The attached service basename inferred from `targetUnit`. */
+  readonly targetServiceName: TimerTargetServiceName<TOptions>;
+  /** The unit name this timer activates, explicit or implicit. */
+  readonly targetUnit: TimerTargetUnit<TOptions>;
+  /** The `[Timer]` section payload. */
+  readonly timer: TOptions[`timer`];
+  /** Optional `[Unit]` section metadata and dependency configuration. */
+  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.
+   */
+  constructor(options: TOptions & ExactSystemdTimerOptions<TOptions>);
+  /** The canonical unit filename, including the `.timer` suffix. */
+  get filename(): TimerFilename<TOptions[`name`]>;
+  /** Renders the timer as a complete unit file. */
+  render(): string;
+}
+//#endregion
+//#region src/main/types.d.ts
+type ScalarDirectiveValue = string | number | boolean;
+type ScalarDirectiveValues = ScalarDirectiveValue | readonly ScalarDirectiveValue[];
+type ExecutableDirectiveValue = string | Executable;
+type ExecutableDirectiveValues = ExecutableDirectiveValue | readonly ExecutableDirectiveValue[];
+type UnitValue = ScalarDirectiveValue | Executable;
+type UnitValueList = readonly UnitValue[];
+type UnitSectionValue = UnitValue | UnitValueList | undefined;
+interface CustomDirectiveSection {
+  readonly [key: `X-${string}`]: UnitSectionValue;
+}
+/**
+ * Generic unit-level directives shared by service and timer units.
+ *
+ * Sources:
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.directives.html
+ */
+interface SystemdUnitSection extends CustomDirectiveSection {
+  readonly After?: ScalarDirectiveValues;
+  readonly AllowIsolate?: ScalarDirectiveValues;
+  readonly AssertACPower?: ScalarDirectiveValues;
+  readonly AssertArchitecture?: ScalarDirectiveValues;
+  readonly AssertCPUFeature?: ScalarDirectiveValues;
+  readonly AssertCPUPressure?: ScalarDirectiveValues;
+  readonly AssertCPUs?: ScalarDirectiveValues;
+  readonly AssertCapability?: ScalarDirectiveValues;
+  readonly AssertControlGroupController?: ScalarDirectiveValues;
+  readonly AssertCredential?: ScalarDirectiveValues;
+  readonly AssertDirectoryNotEmpty?: ScalarDirectiveValues;
+  readonly AssertEnvironment?: ScalarDirectiveValues;
+  readonly AssertFileIsExecutable?: ScalarDirectiveValues;
+  readonly AssertFileNotEmpty?: ScalarDirectiveValues;
+  readonly AssertFirstBoot?: ScalarDirectiveValues;
+  readonly AssertGroup?: ScalarDirectiveValues;
+  readonly AssertHost?: ScalarDirectiveValues;
+  readonly AssertIOPressure?: ScalarDirectiveValues;
+  readonly AssertKernelCommandLine?: ScalarDirectiveValues;
+  readonly AssertKernelModuleLoaded?: ScalarDirectiveValues;
+  readonly AssertKernelVersion?: ScalarDirectiveValues;
+  readonly AssertMemory?: ScalarDirectiveValues;
+  readonly AssertMemoryPressure?: ScalarDirectiveValues;
+  readonly AssertNeedsUpdate?: ScalarDirectiveValues;
+  readonly AssertOSRelease?: ScalarDirectiveValues;
+  readonly AssertPathExists?: ScalarDirectiveValues;
+  readonly AssertPathExistsGlob?: ScalarDirectiveValues;
+  readonly AssertPathIsDirectory?: ScalarDirectiveValues;
+  readonly AssertPathIsEncrypted?: ScalarDirectiveValues;
+  readonly AssertPathIsMountPoint?: ScalarDirectiveValues;
+  readonly AssertPathIsReadWrite?: ScalarDirectiveValues;
+  readonly AssertPathIsSocket?: ScalarDirectiveValues;
+  readonly AssertPathIsSymbolicLink?: ScalarDirectiveValues;
+  readonly AssertSecurity?: ScalarDirectiveValues;
+  readonly AssertUser?: ScalarDirectiveValues;
+  readonly AssertVersion?: ScalarDirectiveValues;
+  readonly AssertVirtualization?: ScalarDirectiveValues;
+  readonly Before?: ScalarDirectiveValues;
+  readonly BindsTo?: ScalarDirectiveValues;
+  readonly CollectMode?: ScalarDirectiveValues;
+  readonly ConditionACPower?: ScalarDirectiveValues;
+  readonly ConditionArchitecture?: ScalarDirectiveValues;
+  readonly ConditionCPUFeature?: ScalarDirectiveValues;
+  readonly ConditionCPUPressure?: ScalarDirectiveValues;
+  readonly ConditionCPUs?: ScalarDirectiveValues;
+  readonly ConditionCapability?: ScalarDirectiveValues;
+  readonly ConditionControlGroupController?: ScalarDirectiveValues;
+  readonly ConditionCredential?: ScalarDirectiveValues;
+  readonly ConditionDirectoryNotEmpty?: ScalarDirectiveValues;
+  readonly ConditionEnvironment?: ScalarDirectiveValues;
+  readonly ConditionFileIsExecutable?: ScalarDirectiveValues;
+  readonly ConditionFileNotEmpty?: ScalarDirectiveValues;
+  readonly ConditionFirmware?: ScalarDirectiveValues;
+  readonly ConditionFirstBoot?: ScalarDirectiveValues;
+  readonly ConditionGroup?: ScalarDirectiveValues;
+  readonly ConditionHost?: ScalarDirectiveValues;
+  readonly ConditionIOPressure?: ScalarDirectiveValues;
+  readonly ConditionKernelCommandLine?: ScalarDirectiveValues;
+  readonly ConditionKernelModuleLoaded?: ScalarDirectiveValues;
+  readonly ConditionKernelVersion?: ScalarDirectiveValues;
+  readonly ConditionMemory?: ScalarDirectiveValues;
+  readonly ConditionMemoryPressure?: ScalarDirectiveValues;
+  readonly ConditionNeedsUpdate?: ScalarDirectiveValues;
+  readonly ConditionOSRelease?: ScalarDirectiveValues;
+  readonly ConditionPathExists?: ScalarDirectiveValues;
+  readonly ConditionPathExistsGlob?: ScalarDirectiveValues;
+  readonly ConditionPathIsDirectory?: ScalarDirectiveValues;
+  readonly ConditionPathIsEncrypted?: ScalarDirectiveValues;
+  readonly ConditionPathIsMountPoint?: ScalarDirectiveValues;
+  readonly ConditionPathIsReadWrite?: ScalarDirectiveValues;
+  readonly ConditionPathIsSocket?: ScalarDirectiveValues;
+  readonly ConditionPathIsSymbolicLink?: ScalarDirectiveValues;
+  readonly ConditionSecurity?: ScalarDirectiveValues;
+  readonly ConditionUser?: ScalarDirectiveValues;
+  readonly ConditionVersion?: ScalarDirectiveValues;
+  readonly ConditionVirtualization?: ScalarDirectiveValues;
+  readonly Conflicts?: ScalarDirectiveValues;
+  readonly DefaultDependencies?: ScalarDirectiveValues;
+  readonly Description?: ScalarDirectiveValues;
+  readonly Documentation?: ScalarDirectiveValues;
+  readonly FailureAction?: ScalarDirectiveValues;
+  readonly FailureActionExitStatus?: ScalarDirectiveValues;
+  readonly IgnoreOnIsolate?: ScalarDirectiveValues;
+  readonly JobRunningTimeoutSec?: ScalarDirectiveValues;
+  readonly JobTimeoutAction?: ScalarDirectiveValues;
+  readonly JobTimeoutRebootArgument?: ScalarDirectiveValues;
+  readonly JobTimeoutSec?: ScalarDirectiveValues;
+  readonly JoinsNamespaceOf?: ScalarDirectiveValues;
+  readonly OnFailure?: ScalarDirectiveValues;
+  readonly OnFailureJobMode?: ScalarDirectiveValues;
+  readonly OnSuccess?: ScalarDirectiveValues;
+  readonly OnSuccessJobMode?: ScalarDirectiveValues;
+  readonly PartOf?: ScalarDirectiveValues;
+  readonly PropagatesReloadTo?: ScalarDirectiveValues;
+  readonly PropagatesStopTo?: ScalarDirectiveValues;
+  readonly RebootArgument?: ScalarDirectiveValues;
+  readonly RefuseManualStart?: ScalarDirectiveValues;
+  readonly RefuseManualStop?: ScalarDirectiveValues;
+  readonly ReloadPropagatedFrom?: ScalarDirectiveValues;
+  readonly Requires?: ScalarDirectiveValues;
+  readonly RequiresMountsFor?: ScalarDirectiveValues;
+  readonly Requisite?: ScalarDirectiveValues;
+  readonly SourcePath?: ScalarDirectiveValues;
+  readonly StartLimitAction?: ScalarDirectiveValues;
+  readonly StartLimitBurst?: ScalarDirectiveValues;
+  readonly StartLimitIntervalSec?: ScalarDirectiveValues;
+  readonly StopPropagatedFrom?: ScalarDirectiveValues;
+  readonly StopWhenUnneeded?: ScalarDirectiveValues;
+  readonly SuccessAction?: ScalarDirectiveValues;
+  readonly SuccessActionExitStatus?: ScalarDirectiveValues;
+  readonly SurviveFinalKillSignal?: ScalarDirectiveValues;
+  readonly Upholds?: ScalarDirectiveValues;
+  readonly Wants?: ScalarDirectiveValues;
+  readonly WantsMountsFor?: ScalarDirectiveValues;
+}
+/**
+ * Install-time directives interpreted by `systemctl enable` rather than the
+ * service manager during normal unit execution.
+ *
+ * Sources:
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.directives.html
+ */
+interface SystemdInstallSection extends CustomDirectiveSection {
+  readonly Alias?: ScalarDirectiveValues;
+  readonly Also?: ScalarDirectiveValues;
+  readonly DefaultInstance?: ScalarDirectiveValues;
+  readonly RequiredBy?: ScalarDirectiveValues;
+  readonly UpheldBy?: ScalarDirectiveValues;
+  readonly WantedBy?: ScalarDirectiveValues;
+}
+/**
+ * Timer-specific directives for `[Timer]` sections.
+ *
+ * Sources:
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.timer.html
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.directives.html
+ */
+interface SystemdTimerSection extends CustomDirectiveSection {
+  readonly AccuracySec?: ScalarDirectiveValues;
+  readonly DeferReactivation?: ScalarDirectiveValues;
+  readonly FixedRandomDelay?: ScalarDirectiveValues;
+  readonly OnActiveSec?: ScalarDirectiveValues;
+  readonly OnBootSec?: ScalarDirectiveValues;
+  readonly OnCalendar?: ScalarDirectiveValues;
+  readonly OnClockChange?: ScalarDirectiveValues;
+  readonly OnStartupSec?: ScalarDirectiveValues;
+  readonly OnTimezoneChange?: ScalarDirectiveValues;
+  readonly OnUnitActiveSec?: ScalarDirectiveValues;
+  readonly OnUnitInactiveSec?: ScalarDirectiveValues;
+  readonly Persistent?: ScalarDirectiveValues;
+  readonly RandomizedDelaySec?: ScalarDirectiveValues;
+  readonly RandomizedOffsetSec?: ScalarDirectiveValues;
+  readonly RemainAfterElapse?: ScalarDirectiveValues;
+  readonly Unit?: ScalarDirectiveValues;
+  readonly WakeSystem?: ScalarDirectiveValues;
+}
+/**
+ * Service-specific and shared execution directives for `[Service]` sections.
+ *
+ * This interface includes:
+ * - directives from `systemd.service(5)`
+ * - execution-environment directives from `systemd.exec(5)`
+ * - kill-behaviour directives from `systemd.kill(5)`
+ * - resource-control directives from `systemd.resource-control(5)`
+ *
+ * Sources:
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.kill.html
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd.directives.html
+ */
+interface SystemdServiceSection extends CustomDirectiveSection {
+  readonly AllowedCPUs?: ScalarDirectiveValues;
+  readonly AllowedMemoryNodes?: ScalarDirectiveValues;
+  readonly AmbientCapabilities?: ScalarDirectiveValues;
+  readonly AppArmorProfile?: ScalarDirectiveValues;
+  readonly BPFDelegateAttachments?: ScalarDirectiveValues;
+  readonly BPFDelegateCommands?: ScalarDirectiveValues;
+  readonly BPFDelegateMaps?: ScalarDirectiveValues;
+  readonly BPFDelegatePrograms?: ScalarDirectiveValues;
+  readonly BPFProgram?: ScalarDirectiveValues;
+  readonly BindLogSockets?: ScalarDirectiveValues;
+  readonly BindNetworkInterface?: ScalarDirectiveValues;
+  readonly BindPaths?: ScalarDirectiveValues;
+  readonly BindReadOnlyPaths?: ScalarDirectiveValues;
+  readonly BusName?: ScalarDirectiveValues;
+  readonly CPUAffinity?: ScalarDirectiveValues;
+  readonly CPUQuota?: ScalarDirectiveValues;
+  readonly CPUQuotaPeriodSec?: ScalarDirectiveValues;
+  readonly CPUSchedulingPolicy?: ScalarDirectiveValues;
+  readonly CPUSchedulingPriority?: ScalarDirectiveValues;
+  readonly CPUSchedulingResetOnFork?: ScalarDirectiveValues;
+  readonly CPUWeight?: ScalarDirectiveValues;
+  readonly CacheDirectory?: ScalarDirectiveValues;
+  readonly CacheDirectoryAccounting?: ScalarDirectiveValues;
+  readonly CacheDirectoryMode?: ScalarDirectiveValues;
+  readonly CacheDirectoryQuota?: ScalarDirectiveValues;
+  readonly CapabilityBoundingSet?: ScalarDirectiveValues;
+  readonly ConfigurationDirectory?: ScalarDirectiveValues;
+  readonly ConfigurationDirectoryMode?: ScalarDirectiveValues;
+  readonly CoredumpFilter?: ScalarDirectiveValues;
+  readonly CoredumpReceive?: ScalarDirectiveValues;
+  readonly Delegate?: ScalarDirectiveValues;
+  readonly DelegateNamespaces?: ScalarDirectiveValues;
+  readonly DelegateSubgroup?: ScalarDirectiveValues;
+  readonly DeviceAllow?: ScalarDirectiveValues;
+  readonly DevicePolicy?: ScalarDirectiveValues;
+  readonly DisableControllers?: ScalarDirectiveValues;
+  readonly DynamicUser?: ScalarDirectiveValues;
+  readonly Environment?: ScalarDirectiveValues;
+  readonly EnvironmentFile?: ScalarDirectiveValues;
+  readonly ExecCondition?: ExecutableDirectiveValues;
+  readonly ExecPaths?: ScalarDirectiveValues;
+  readonly ExecReload?: ExecutableDirectiveValues;
+  readonly ExecReloadPost?: ExecutableDirectiveValues;
+  readonly ExecSearchPath?: ScalarDirectiveValues;
+  readonly ExecStart?: ExecutableDirectiveValues;
+  readonly ExecStartPost?: ExecutableDirectiveValues;
+  readonly ExecStartPre?: ExecutableDirectiveValues;
+  readonly ExecStop?: ExecutableDirectiveValues;
+  readonly ExecStopPost?: ExecutableDirectiveValues;
+  readonly ExitType?: ScalarDirectiveValues;
+  readonly ExtensionDirectories?: ScalarDirectiveValues;
+  readonly ExtensionImagePolicy?: ScalarDirectiveValues;
+  readonly ExtensionImages?: ScalarDirectiveValues;
+  readonly FileDescriptorStoreMax?: ScalarDirectiveValues;
+  readonly FileDescriptorStorePreserve?: ScalarDirectiveValues;
+  readonly FinalKillSignal?: ScalarDirectiveValues;
+  readonly Group?: ScalarDirectiveValues;
+  readonly GuessMainPID?: ScalarDirectiveValues;
+  readonly IOAccounting?: ScalarDirectiveValues;
+  readonly IODeviceLatencyTargetSec?: ScalarDirectiveValues;
+  readonly IODeviceWeight?: ScalarDirectiveValues;
+  readonly IOReadBandwidthMax?: ScalarDirectiveValues;
+  readonly IOReadIOPSMax?: ScalarDirectiveValues;
+  readonly IOSchedulingClass?: ScalarDirectiveValues;
+  readonly IOSchedulingPriority?: ScalarDirectiveValues;
+  readonly IOWeight?: ScalarDirectiveValues;
+  readonly IOWriteBandwidthMax?: ScalarDirectiveValues;
+  readonly IOWriteIOPSMax?: ScalarDirectiveValues;
+  readonly IPAccounting?: ScalarDirectiveValues;
+  readonly IPAddressAllow?: ScalarDirectiveValues;
+  readonly IPAddressDeny?: ScalarDirectiveValues;
+  readonly IPEgressFilterPath?: ScalarDirectiveValues;
+  readonly IPIngressFilterPath?: ScalarDirectiveValues;
+  readonly IPCNamespacePath?: ScalarDirectiveValues;
+  readonly IgnoreSIGPIPE?: ScalarDirectiveValues;
+  readonly ImportCredential?: ScalarDirectiveValues;
+  readonly InaccessiblePaths?: ScalarDirectiveValues;
+  readonly KeyringMode?: ScalarDirectiveValues;
+  readonly KillMode?: ScalarDirectiveValues;
+  readonly KillSignal?: ScalarDirectiveValues;
+  readonly LimitAS?: ScalarDirectiveValues;
+  readonly LimitCORE?: ScalarDirectiveValues;
+  readonly LimitCPU?: ScalarDirectiveValues;
+  readonly LimitDATA?: ScalarDirectiveValues;
+  readonly LimitFSIZE?: ScalarDirectiveValues;
+  readonly LimitLOCKS?: ScalarDirectiveValues;
+  readonly LimitMEMLOCK?: ScalarDirectiveValues;
+  readonly LimitMSGQUEUE?: ScalarDirectiveValues;
+  readonly LimitNICE?: ScalarDirectiveValues;
+  readonly LimitNOFILE?: ScalarDirectiveValues;
+  readonly LimitNPROC?: ScalarDirectiveValues;
+  readonly LimitRSS?: ScalarDirectiveValues;
+  readonly LimitRTPRIO?: ScalarDirectiveValues;
+  readonly LimitRTTIME?: ScalarDirectiveValues;
+  readonly LimitSIGPENDING?: ScalarDirectiveValues;
+  readonly LimitSTACK?: ScalarDirectiveValues;
+  readonly LoadCredential?: ScalarDirectiveValues;
+  readonly LoadCredentialEncrypted?: ScalarDirectiveValues;
+  readonly LockPersonality?: ScalarDirectiveValues;
+  readonly LogExtraFields?: ScalarDirectiveValues;
+  readonly LogFilterPatterns?: ScalarDirectiveValues;
+  readonly LogLevelMax?: ScalarDirectiveValues;
+  readonly LogNamespace?: ScalarDirectiveValues;
+  readonly LogRateLimitBurst?: ScalarDirectiveValues;
+  readonly LogRateLimitIntervalSec?: ScalarDirectiveValues;
+  readonly LogsDirectory?: ScalarDirectiveValues;
+  readonly LogsDirectoryAccounting?: ScalarDirectiveValues;
+  readonly LogsDirectoryMode?: ScalarDirectiveValues;
+  readonly LogsDirectoryQuota?: ScalarDirectiveValues;
+  readonly ManagedOOMMemoryPressure?: ScalarDirectiveValues;
+  readonly ManagedOOMMemoryPressureDurationSec?: ScalarDirectiveValues;
+  readonly ManagedOOMMemoryPressureLimit?: ScalarDirectiveValues;
+  readonly ManagedOOMPreference?: ScalarDirectiveValues;
+  readonly ManagedOOMSwap?: ScalarDirectiveValues;
+  readonly MemoryAccounting?: ScalarDirectiveValues;
+  readonly MemoryDenyWriteExecute?: ScalarDirectiveValues;
+  readonly MemoryHigh?: ScalarDirectiveValues;
+  readonly MemoryKSM?: ScalarDirectiveValues;
+  readonly MemoryLow?: ScalarDirectiveValues;
+  readonly MemoryMax?: ScalarDirectiveValues;
+  readonly MemoryMin?: ScalarDirectiveValues;
+  readonly MemoryPressureThresholdSec?: ScalarDirectiveValues;
+  readonly MemoryPressureWatch?: ScalarDirectiveValues;
+  readonly MemorySwapMax?: ScalarDirectiveValues;
+  readonly MemoryTHP?: ScalarDirectiveValues;
+  readonly MemoryZSwapMax?: ScalarDirectiveValues;
+  readonly MemoryZSwapWriteback?: ScalarDirectiveValues;
+  readonly MountAPIVFS?: ScalarDirectiveValues;
+  readonly MountFlags?: ScalarDirectiveValues;
+  readonly MountImagePolicy?: ScalarDirectiveValues;
+  readonly MountImages?: ScalarDirectiveValues;
+  readonly NFTSet?: ScalarDirectiveValues;
+  readonly NUMAMask?: ScalarDirectiveValues;
+  readonly NUMAPolicy?: ScalarDirectiveValues;
+  readonly NetworkNamespacePath?: ScalarDirectiveValues;
+  readonly Nice?: ScalarDirectiveValues;
+  readonly NoExecPaths?: ScalarDirectiveValues;
+  readonly NoNewPrivileges?: ScalarDirectiveValues;
+  readonly NonBlocking?: ScalarDirectiveValues;
+  readonly NotifyAccess?: ScalarDirectiveValues;
+  readonly OOMPolicy?: ScalarDirectiveValues;
+  readonly OOMScoreAdjust?: ScalarDirectiveValues;
+  readonly OpenFile?: ScalarDirectiveValues;
+  readonly PAMName?: ScalarDirectiveValues;
+  readonly PIDFile?: ScalarDirectiveValues;
+  readonly PassEnvironment?: ScalarDirectiveValues;
+  readonly Personality?: ScalarDirectiveValues;
+  readonly PrivateBPF?: ScalarDirectiveValues;
+  readonly PrivateDevices?: ScalarDirectiveValues;
+  readonly PrivateIPC?: ScalarDirectiveValues;
+  readonly PrivateMounts?: ScalarDirectiveValues;
+  readonly PrivateNetwork?: ScalarDirectiveValues;
+  readonly PrivatePIDs?: ScalarDirectiveValues;
+  readonly PrivateTmp?: ScalarDirectiveValues;
+  readonly PrivateUsers?: ScalarDirectiveValues;
+  readonly ProcSubset?: ScalarDirectiveValues;
+  readonly ProtectClock?: ScalarDirectiveValues;
+  readonly ProtectControlGroups?: ScalarDirectiveValues;
+  readonly ProtectHome?: ScalarDirectiveValues;
+  readonly ProtectHostname?: ScalarDirectiveValues;
+  readonly ProtectKernelLogs?: ScalarDirectiveValues;
+  readonly ProtectKernelModules?: ScalarDirectiveValues;
+  readonly ProtectKernelTunables?: ScalarDirectiveValues;
+  readonly ProtectProc?: ScalarDirectiveValues;
+  readonly ProtectSystem?: ScalarDirectiveValues;
+  readonly ReadOnlyPaths?: ScalarDirectiveValues;
+  readonly ReadWritePaths?: ScalarDirectiveValues;
+  readonly RefreshOnReload?: ScalarDirectiveValues;
+  readonly ReloadSignal?: ScalarDirectiveValues;
+  readonly RemainAfterExit?: ScalarDirectiveValues;
+  readonly RemoveIPC?: ScalarDirectiveValues;
+  readonly Restart?: ScalarDirectiveValues;
+  readonly RestartForceExitStatus?: ScalarDirectiveValues;
+  readonly RestartKillSignal?: ScalarDirectiveValues;
+  readonly RestartMaxDelaySec?: ScalarDirectiveValues;
+  readonly RestartMode?: ScalarDirectiveValues;
+  readonly RestartPreventExitStatus?: ScalarDirectiveValues;
+  readonly RestartSec?: ScalarDirectiveValues;
+  readonly RestartSteps?: ScalarDirectiveValues;
+  readonly RestrictAddressFamilies?: ScalarDirectiveValues;
+  readonly RestrictFileSystems?: ScalarDirectiveValues;
+  readonly RestrictNamespaces?: ScalarDirectiveValues;
+  readonly RestrictNetworkInterfaces?: ScalarDirectiveValues;
+  readonly RestrictRealtime?: ScalarDirectiveValues;
+  readonly RestrictSUIDSGID?: ScalarDirectiveValues;
+  readonly RootDirectory?: ScalarDirectiveValues;
+  readonly RootDirectoryStartOnly?: ScalarDirectiveValues;
+  readonly RootEphemeral?: ScalarDirectiveValues;
+  readonly RootHash?: ScalarDirectiveValues;
+  readonly RootHashSignature?: ScalarDirectiveValues;
+  readonly RootImage?: ScalarDirectiveValues;
+  readonly RootImageOptions?: ScalarDirectiveValues;
+  readonly RootImagePolicy?: ScalarDirectiveValues;
+  readonly RootMStack?: ScalarDirectiveValues;
+  readonly RootVerity?: ScalarDirectiveValues;
+  readonly RuntimeDirectory?: ScalarDirectiveValues;
+  readonly RuntimeDirectoryMode?: ScalarDirectiveValues;
+  readonly RuntimeDirectoryPreserve?: ScalarDirectiveValues;
+  readonly RuntimeMaxSec?: ScalarDirectiveValues;
+  readonly RuntimeRandomizedExtraSec?: ScalarDirectiveValues;
+  readonly SELinuxContext?: ScalarDirectiveValues;
+  readonly SecureBits?: ScalarDirectiveValues;
+  readonly SendSIGHUP?: ScalarDirectiveValues;
+  readonly SendSIGKILL?: ScalarDirectiveValues;
+  readonly SetCredential?: ScalarDirectiveValues;
+  readonly SetCredentialEncrypted?: ScalarDirectiveValues;
+  readonly SetLoginEnvironment?: ScalarDirectiveValues;
+  readonly Slice?: ScalarDirectiveValues;
+  readonly SmackProcessLabel?: ScalarDirectiveValues;
+  readonly SocketBindAllow?: ScalarDirectiveValues;
+  readonly SocketBindDeny?: ScalarDirectiveValues;
+  readonly Sockets?: ScalarDirectiveValues;
+  readonly StandardError?: ScalarDirectiveValues;
+  readonly StandardInput?: ScalarDirectiveValues;
+  readonly StandardInputData?: ScalarDirectiveValues;
+  readonly StandardInputText?: ScalarDirectiveValues;
+  readonly StandardOutput?: ScalarDirectiveValues;
+  readonly StartupAllowedCPUs?: ScalarDirectiveValues;
+  readonly StartupAllowedMemoryNodes?: ScalarDirectiveValues;
+  readonly StartupCPUWeight?: ScalarDirectiveValues;
+  readonly StartupIOWeight?: ScalarDirectiveValues;
+  readonly StartupMemoryHigh?: ScalarDirectiveValues;
+  readonly StartupMemoryLow?: ScalarDirectiveValues;
+  readonly StartupMemoryMax?: ScalarDirectiveValues;
+  readonly StartupMemorySwapMax?: ScalarDirectiveValues;
+  readonly StartupMemoryZSwapMax?: ScalarDirectiveValues;
+  readonly StateDirectory?: ScalarDirectiveValues;
+  readonly StateDirectoryAccounting?: ScalarDirectiveValues;
+  readonly StateDirectoryMode?: ScalarDirectiveValues;
+  readonly StateDirectoryQuota?: ScalarDirectiveValues;
+  readonly SuccessExitStatus?: ScalarDirectiveValues;
+  readonly SupplementaryGroups?: ScalarDirectiveValues;
+  readonly SyslogFacility?: ScalarDirectiveValues;
+  readonly SyslogIdentifier?: ScalarDirectiveValues;
+  readonly SyslogLevel?: ScalarDirectiveValues;
+  readonly SyslogLevelPrefix?: ScalarDirectiveValues;
+  readonly SystemCallArchitectures?: ScalarDirectiveValues;
+  readonly SystemCallErrorNumber?: ScalarDirectiveValues;
+  readonly SystemCallFilter?: ScalarDirectiveValues;
+  readonly SystemCallLog?: ScalarDirectiveValues;
+  readonly TTYColumns?: ScalarDirectiveValues;
+  readonly TTYPath?: ScalarDirectiveValues;
+  readonly TTYReset?: ScalarDirectiveValues;
+  readonly TTYRows?: ScalarDirectiveValues;
+  readonly TTYVHangup?: ScalarDirectiveValues;
+  readonly TTYVTDisallocate?: ScalarDirectiveValues;
+  readonly TasksAccounting?: ScalarDirectiveValues;
+  readonly TasksMax?: ScalarDirectiveValues;
+  readonly TemporaryFileSystem?: ScalarDirectiveValues;
+  readonly TimeoutAbortSec?: ScalarDirectiveValues;
+  readonly TimeoutSec?: ScalarDirectiveValues;
+  readonly TimeoutCleanSec?: ScalarDirectiveValues;
+  readonly TimeoutStartFailureMode?: ScalarDirectiveValues;
+  readonly TimeoutStartSec?: ScalarDirectiveValues;
+  readonly TimeoutStopFailureMode?: ScalarDirectiveValues;
+  readonly TimeoutStopSec?: ScalarDirectiveValues;
+  readonly TimerSlackNSec?: ScalarDirectiveValues;
+  readonly UMask?: ScalarDirectiveValues;
+  readonly USBFunctionDescriptors?: ScalarDirectiveValues;
+  readonly USBFunctionStrings?: ScalarDirectiveValues;
+  readonly UnsetEnvironment?: ScalarDirectiveValues;
+  readonly User?: ScalarDirectiveValues;
+  readonly UserNamespacePath?: ScalarDirectiveValues;
+  readonly UtmpIdentifier?: ScalarDirectiveValues;
+  readonly UtmpMode?: ScalarDirectiveValues;
+  readonly Type?: ScalarDirectiveValues;
+  readonly WatchdogSec?: ScalarDirectiveValues;
+  readonly WatchdogSignal?: ScalarDirectiveValues;
+  readonly WorkingDirectory?: ScalarDirectiveValues;
+}
+/**
+ * @deprecated Use one of the specific section interfaces instead:
+ * `SystemdUnitSection`, `SystemdInstallSection`, `SystemdServiceSection`, or
+ * `SystemdTimerSection`.
+ */
 interface UnitSection {
-  readonly [key: string]: UnitValue | readonly UnitValue[] | undefined;
+  readonly [key: string]: UnitSectionValue;
 }
 interface SystemdServiceOptions {
-  readonly install?: UnitSection;
+  readonly install?: SystemdInstallSection;
   readonly name: string;
-  readonly service: UnitSection;
-  readonly unit?: UnitSection;
+  readonly service: SystemdServiceSection;
+  readonly unit?: SystemdUnitSection;
 }
 interface SystemdTimerOptions {
-  readonly install?: UnitSection;
+  readonly install?: SystemdInstallSection;
   readonly name: string;
-  readonly timer: UnitSection;
-  readonly unit?: UnitSection;
+  readonly timer: SystemdTimerSection;
+  readonly unit?: SystemdUnitSection;
 }
+type NoExtraKeys<TActual, TShape> = TActual & { readonly [K in Exclude<keyof TActual, keyof TShape>]: never };
+type ExactOptionalSection<TSection, TShape> = TSection extends undefined ? undefined : NoExtraKeys<TSection, TShape>;
+type ExactSystemdServiceOptions<TOptions extends SystemdServiceOptions> = NoExtraKeys<Omit<TOptions, "install" | "service" | "unit"> & {
+  readonly install?: ExactOptionalSection<TOptions[`install`], SystemdInstallSection>;
+  readonly service: NoExtraKeys<TOptions[`service`], SystemdServiceSection>;
+  readonly unit?: ExactOptionalSection<TOptions[`unit`], SystemdUnitSection>;
+}, SystemdServiceOptions>;
+type ExactSystemdTimerOptions<TOptions extends SystemdTimerOptions> = NoExtraKeys<Omit<TOptions, "install" | "timer" | "unit"> & {
+  readonly install?: ExactOptionalSection<TOptions[`install`], SystemdInstallSection>;
+  readonly timer: NoExtraKeys<TOptions[`timer`], SystemdTimerSection>;
+  readonly unit?: ExactOptionalSection<TOptions[`unit`], SystemdUnitSection>;
+}, SystemdTimerOptions>;
 interface SystemdOptions {
   readonly executor?: CommandExecutor;
   readonly linkUnits?: boolean;
@@ -69,64 +630,219 @@ type MismatchedTimers<TUnits extends readonly SystemdUnit[]> = TUnits[number] ex
 type HasServices<TUnits extends readonly SystemdUnit[]> = [ServiceNamesIn<TUnits>] extends [never] ? false : true;
 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;
-type UnitValue = string | number | boolean | Executable;
+//#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;
 }
-declare class SystemdService<const TOptions extends SystemdServiceOptions = SystemdServiceOptions> {
-  readonly install: TOptions[`install`] | undefined;
-  readonly name: ServiceBaseName<TOptions[`name`]>;
-  readonly options: Readonly<TOptions>;
-  readonly service: TOptions[`service`];
-  readonly unit: TOptions[`unit`] | undefined;
-  constructor(options: TOptions);
-  get filename(): ServiceFilename<TOptions[`name`]>;
-  render(): string;
-}
-declare class SystemdTimer<const TOptions extends SystemdTimerOptions = SystemdTimerOptions> {
-  readonly install: TOptions[`install`] | undefined;
-  readonly name: TimerBaseName<TOptions[`name`]>;
-  readonly options: Readonly<TOptions>;
-  readonly targetServiceName: TimerTargetServiceName<TOptions>;
-  readonly targetUnit: TimerTargetUnit<TOptions>;
-  readonly timer: TOptions[`timer`];
-  readonly unit: TOptions[`unit`] | undefined;
-  constructor(options: TOptions);
-  get filename(): TimerFilename<TOptions[`name`]>;
-  render(): string;
-}
+/**
+ * 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
+/**
+ * Helpers for sending `sd_notify` state updates to systemd.
+ *
+ * These helpers send notification payloads to the socket identified by
+ * `NOTIFY_SOCKET`, or to `options.socketPath` when one is provided explicitly.
+ * They are useful both in real services and in tests that want to observe
+ * readiness or watchdog traffic directly.
+ *
+ * Source:
+ * - https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd-notify.html
+ */
+declare const notify: {
+  /**
+   * Sends `READY=1` to systemd.
+   *
+   * Use this when a `Type=notify` service has completed its startup work and is
+   * ready to be considered fully started. If `options.status` is provided, it is
+   * sent as an additional `STATUS=...` field.
+   */
+  ready(options?: NotifyOptions): Promise<void>;
+  /**
+   * Sends `WATCHDOG=1` to systemd.
+   *
+   * Use this when a service configured with `WatchdogSec=` needs to emit a
+   * watchdog heartbeat. If `options.pid` is provided, it is sent as
+   * `MAINPID=...`, and `options.status` is forwarded as `STATUS=...`.
+   */
+  watchdog(options?: NotifyOptions): Promise<void>;
+};
+//#endregion
+//#region src/main/systemd.d.ts
+/**
+ * The result of installing one or more units with {@link Systemd.install}.
+ *
+ * It records the installation directory and the on-disk path associated with
+ * each installed unit.
+ */
 declare class SystemdInstallResult<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;
 }
+/**
+ * A configured interface to a specific systemd environment.
+ *
+ * `Systemd` combines unit-file materialization with a command execution
+ * strategy. It knows which scope it is targeting, where unit files should be
+ * written, and how `systemctl` should be invoked.
+ *
+ * This abstraction is intentionally close to `systemctl` concepts while still
+ * accepting full unit definitions instead of loose unit-name strings.
+ */
 declare class Systemd {
+  /** Command executor used for `systemctl` and related subprocess calls. */
   readonly executor: CommandExecutor;
+  /** Whether units should be linked into systemd before manager operations. */
   readonly linkUnits: boolean;
+  /** The target manager scope, either `system` or `user`. */
   readonly scope: `system` | `user`;
+  /** The directory used when materializing unit files. */
   readonly unitDir: string;
+  /**
+   * Creates a configured `Systemd` facade.
+   *
+   * By default, this targets the system scope and `/etc/systemd/system`. Use
+   * `scope: "user"` or an explicit `unitDir` to target a different manager or
+   * unit-file location.
+   */
   constructor(options?: SystemdOptions);
-  install<const TUnits extends readonly SystemdUnit[]>(...units: ValidInstallUnits<TUnits>): Promise<SystemdInstallResult<TUnits>>;
+  /**
+   * 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.
+   */
+  install<const TUnits extends readonly SystemdUnit[]>(...units: TUnits & ValidInstallUnits<TUnits>): Promise<SystemdInstallResult<TUnits>>;
+  /**
+   * Enables one or more units via `systemctl enable`.
+   *
+   * When `linkUnits` is enabled, this first links installed 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>;
+  /**
+   * Starts a unit and returns a parsed `systemctl show` snapshot of its final
+   * observed state.
+   *
+   * 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>;
-  logs(_unit: SystemdUnit, _options?: LogsOptions): Promise<string>;
+  /**
+   * Reads recent output for a managed unit.
+   *
+   * If the unit is configured with file-backed `StandardOutput` or
+   * `StandardError`, this reads directly from that file. Otherwise it falls back
+   * to `systemctl status --lines ...`.
+   */
+  logs(unit: SystemdUnit, options?: LogsOptions): Promise<string>;
+  /** Returns the on-disk unit-file path this instance uses for the given unit. */
   pathFor(unit: SystemdUnit): string;
   private prepareUnits;
   private scopeArgs;
   private collectLinkPaths;
 }
+/**
+ * Returns the lazily created default `Systemd` instance.
+ *
+ * The default instance uses the library defaults for scope, unit directory, and
+ * command execution.
+ */
 declare function defaultSystemd(): Systemd;
-declare const notify: {
-  ready(options?: NotifyOptions): Promise<void>;
-  watchdog(options?: NotifyOptions): Promise<void>;
-};
-declare function defineExecutable(fn: () => void | Promise<void>, options?: ExecutableOptions): Executable;
+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
+/**
+ * Internal helpers are exposed for advanced use, but they are not a stable public API.
+ * Expect breaking changes here outside the package's normal compatibility guarantees.
+ */
+declare const Internal: typeof internal_d_exports;
 //#endregion
-export { AnySystemdService, AnySystemdTimer, CommandExecutor, CommandResult, Executable, ExecutableOptions, InstalledUnit, LogsOptions, NotifyOptions, StartResult, Systemd, SystemdInstallResult, SystemdOptions, SystemdService, SystemdServiceOptions, SystemdTimer, SystemdTimerOptions, SystemdUnit, UnitSection, UnitValue, defaultSystemd, defineExecutable, notify };
+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 };