feat(systemd): land Systemd trait, LiveSystemd, MockSystemd, parsers (#12)

Plan §6.8 — third M1 Week 2 adapter probe path. Inventory only at M1;
enable / disable / mask / restart arrive with M2 per Plan §7.3.

Public surface:

- pub trait Systemd { fn inventory(&self) -> Result<ServiceInventory, SystemdError>; }
- pub struct LiveSystemd with new() / with_binary() / binary().
- pub struct MockSystemd (test-mocks feature) with new() / with_inventory().
- pub fn parse_list_unit_files(&str) -> (BTreeSet<String>, BTreeSet<String>, BTreeSet<String>)
  returning (enabled, disabled, masked).
- pub fn parse_list_units(&str) -> BTreeSet<String> returning the
  loaded+active set.
- pub fn compose_inventory(unit_files, units) -> ServiceInventory.
- pub enum SystemdError — NotInPath, Io, InvocationFailed, NotUtf8.

Parser semantics:

- list-unit-files: enabled and enabled-runtime → enabled set;
  disabled → disabled; masked and masked-runtime → masked. static,
  alias, indirect, generated, transient skipped (not user-configurable
  enable values).
- list-units: filter LOAD == "loaded" && ACTIVE == "active" so the
  active set excludes not-found, error, masked, and inactive units.

LiveSystemd invokes:
- systemctl list-unit-files --no-pager --no-legend
- systemctl list-units --no-pager --no-legend --all --plain

Tests (10 passing):
- inventory: list_unit_files_distinguishes_enabled_disabled_masked,
  list_unit_files_skips_static_alias_indirect,
  list_units_filters_to_loaded_active, empty_outputs_yield_empty_inventory,
  compose_combines_both_streams, truncated_lines_are_skipped.
- live: systemctl_not_in_path_error_class,
  live_systemd_inventory_succeeds_when_systemctl_present (silent-skips
  if systemctl missing — CI runners have it).
- mock: empty_mock_yields_empty_inventory, with_inventory_round_trips.

Verification:
- cargo test -p pearlite-systemd  (10 passed; 0 failed)
- cargo clippy --workspace --all-targets -- -D warnings  (zero warnings)
- cargo fmt --all --check
- scripts/ci/check-spdx.sh
- pearlite-audit check .  (1 check, 0 violations)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

crates/pearlite-systemd/Cargo.toml

@@ -11,4 +11,9 @@ repository.workspace = true
 [lints]
 workspace = true
 
+[features]
+test-mocks = []
+
 [dependencies]
+pearlite-schema = { path = "../pearlite-schema", version = "0.1" }
+thiserror = { workspace = true }

crates/pearlite-systemd/src/errors.rs

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Mohamed Hammad
+
+//! Errors emitted by `pearlite-systemd`.
+
+use thiserror::Error;
+
+/// Errors emitted while invoking `systemctl` or parsing its output.
+#[derive(Debug, Error)]
+pub enum SystemdError {
+    /// The configured `systemctl` binary could not be spawned. Usually
+    /// a Class 1 preflight failure: every supported host has systemd.
+    #[error("systemctl binary not found: {hint}")]
+    NotInPath {
+        /// Hint string with a runnable command.
+        hint: &'static str,
+    },
+    /// `std::io` error during spawn or stdout capture.
+    #[error("I/O error invoking systemctl: {0}")]
+    Io(#[from] std::io::Error),
+    /// `systemctl` exited non-zero.
+    #[error("systemctl exited with code {code}:\n{stderr}")]
+    InvocationFailed {
+        /// Process exit code.
+        code: i32,
+        /// Captured stderr verbatim.
+        stderr: String,
+    },
+    /// `systemctl` stdout was not valid UTF-8.
+    #[error("systemctl stdout was not valid UTF-8: {0}")]
+    NotUtf8(#[from] std::string::FromUtf8Error),
+}

crates/pearlite-systemd/src/inventory.rs

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Mohamed Hammad
+
+//! `systemctl list-unit-files` + `systemctl list-units` parsers and
+//! composition into a [`ServiceInventory`].
+
+use pearlite_schema::ServiceInventory;
+use std::collections::BTreeSet;
+
+/// Parse the stdout of
+/// `systemctl list-unit-files --no-pager --no-legend` into the three
+/// disjoint state buckets `(enabled, disabled, masked)`.
+///
+/// `enabled-runtime` and `masked-runtime` are folded into the
+/// non-runtime variants — the difference matters at apply time but not
+/// for drift detection.
+///
+/// `static`, `alias`, `indirect`, `generated`, and `transient` are
+/// silently skipped: those states are not user-configurable enable
+/// values and never appear in declared service config.
+#[must_use]
+pub fn parse_list_unit_files(
+    stdout: &str,
+) -> (BTreeSet<String>, BTreeSet<String>, BTreeSet<String>) {
+    let mut enabled = BTreeSet::new();
+    let mut disabled = BTreeSet::new();
+    let mut masked = BTreeSet::new();
+    for line in stdout.lines() {
+        let mut iter = line.split_whitespace();
+        let Some(unit) = iter.next() else { continue };
+        let Some(state) = iter.next() else { continue };
+        match state {
+            "enabled" | "enabled-runtime" => {
+                enabled.insert(unit.to_owned());
+            }
+            "disabled" => {
+                disabled.insert(unit.to_owned());
+            }
+            "masked" | "masked-runtime" => {
+                masked.insert(unit.to_owned());
+            }
+            _ => {} // static / alias / indirect / generated / transient
+        }
+    }
+    (enabled, disabled, masked)
+}
+
+/// Parse the stdout of
+/// `systemctl list-units --no-pager --no-legend --all --plain` into the
+/// set of currently active, loaded units.
+///
+/// Filter: `LOAD == loaded && ACTIVE == active`. Units that are
+/// not-found, error, masked, or inactive are skipped.
+#[must_use]
+pub fn parse_list_units(stdout: &str) -> BTreeSet<String> {
+    let mut active = BTreeSet::new();
+    for line in stdout.lines() {
+        let mut iter = line.split_whitespace();
+        let Some(unit) = iter.next() else { continue };
+        let Some(load) = iter.next() else { continue };
+        let Some(active_state) = iter.next() else {
+            continue;
+        };
+        if load == "loaded" && active_state == "active" {
+            active.insert(unit.to_owned());
+        }
+    }
+    active
+}
+
+/// Combine `list-unit-files` and `list-units` outputs into one
+/// [`ServiceInventory`].
+#[must_use]
+pub fn compose_inventory(unit_files: &str, units: &str) -> ServiceInventory {
+    let (enabled, disabled, masked) = parse_list_unit_files(unit_files);
+    let active = parse_list_units(units);
+    ServiceInventory {
+        enabled,
+        disabled,
+        masked,
+        active,
+    }
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::expect_used,
+    clippy::unwrap_used,
+    clippy::panic,
+    reason = "tests may use expect()/unwrap()/panic!() per Plan §4.2 + CLAUDE.md"
+)]
+mod tests {
+    use super::*;
+
+    const UNIT_FILES: &str = "\
+nginx.service                              enabled        enabled
+sshd.service                               enabled        enabled
+NetworkManager.service                     enabled-runtime enabled
+bluetooth.service                          disabled       enabled
+systemd-resolved.service                   masked         enabled
+shutdown.target                            static         -
+console-getty.service                      indirect       -
+systemd-tmpfiles-setup.service             alias          -
+";
+
+    const UNITS: &str = "\
+nginx.service                       loaded    active   running   A high-performance web server
+sshd.service                        loaded    active   running   OpenBSD Secure Shell server
+bluetooth.service                   loaded    inactive dead      Bluetooth service
+systemd-resolved.service            masked    inactive dead      systemd-resolved.service
+not-found.service                   not-found inactive dead      not-found.service
+";
+
+    #[test]
+    fn list_unit_files_distinguishes_enabled_disabled_masked() {
+        let (enabled, disabled, masked) = parse_list_unit_files(UNIT_FILES);
+
+        assert_eq!(enabled.len(), 3);
+        assert!(enabled.contains("nginx.service"));
+        assert!(enabled.contains("sshd.service"));
+        assert!(enabled.contains("NetworkManager.service")); // enabled-runtime
+
+        assert_eq!(disabled.len(), 1);
+        assert!(disabled.contains("bluetooth.service"));
+
+        assert_eq!(masked.len(), 1);
+        assert!(masked.contains("systemd-resolved.service"));
+    }
+
+    #[test]
+    fn list_unit_files_skips_static_alias_indirect() {
+        let (enabled, disabled, masked) = parse_list_unit_files(UNIT_FILES);
+        let all: BTreeSet<&str> = enabled
+            .iter()
+            .chain(disabled.iter())
+            .chain(masked.iter())
+            .map(String::as_str)
+            .collect();
+        assert!(!all.contains("shutdown.target"));
+        assert!(!all.contains("console-getty.service"));
+        assert!(!all.contains("systemd-tmpfiles-setup.service"));
+    }
+
+    #[test]
+    fn list_units_filters_to_loaded_active() {
+        let active = parse_list_units(UNITS);
+        assert_eq!(active.len(), 2);
+        assert!(active.contains("nginx.service"));
+        assert!(active.contains("sshd.service"));
+        // Inactive: not active.
+        assert!(!active.contains("bluetooth.service"));
+        // Masked: not loaded.
+        assert!(!active.contains("systemd-resolved.service"));
+        // Not-found: not loaded.
+        assert!(!active.contains("not-found.service"));
+    }
+
+    #[test]
+    fn empty_outputs_yield_empty_inventory() {
+        let inv = compose_inventory("", "");
+        assert!(inv.enabled.is_empty());
+        assert!(inv.disabled.is_empty());
+        assert!(inv.masked.is_empty());
+        assert!(inv.active.is_empty());
+    }
+
+    #[test]
+    fn compose_combines_both_streams() {
+        let inv = compose_inventory(UNIT_FILES, UNITS);
+        assert_eq!(inv.enabled.len(), 3);
+        assert_eq!(inv.disabled.len(), 1);
+        assert_eq!(inv.masked.len(), 1);
+        assert_eq!(inv.active.len(), 2);
+    }
+
+    #[test]
+    fn truncated_lines_are_skipped() {
+        // Defensive: a corrupt or partial line must not panic.
+        let truncated = "nginx.service\nsshd.service enabled\n";
+        let (enabled, _, _) = parse_list_unit_files(truncated);
+        assert_eq!(enabled.len(), 1);
+        assert!(enabled.contains("sshd.service"));
+    }
+}

crates/pearlite-systemd/src/lib.rs

@@ -1,4 +1,25 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Mohamed Hammad
 
-//! systemctl adapter: enable, disable, mask, restart for system and user scopes.
+//! systemctl adapter: enable, disable, mask, restart for system and
+//! user scopes.
+//!
+//! At M1 only the read side ([`Systemd::inventory`]) is implemented.
+//! Apply-side methods (enable, disable, mask, restart) and user-scope
+//! support arrive in M2 per Plan §7.3.
+
+mod errors;
+mod inventory;
+mod live;
+#[cfg(any(test, feature = "test-mocks"))]
+mod mock;
+
+pub use errors::SystemdError;
+pub use inventory::{compose_inventory, parse_list_unit_files, parse_list_units};
+pub use live::{LiveSystemd, Systemd};
+
+#[cfg(feature = "test-mocks")]
+pub use mock::MockSystemd;
+
+#[doc(no_inline)]
+pub use pearlite_schema::ServiceInventory;

crates/pearlite-systemd/src/live.rs

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Mohamed Hammad
+
+//! [`Systemd`] trait + production [`LiveSystemd`] implementation.
+
+use crate::errors::SystemdError;
+use crate::inventory::compose_inventory;
+use pearlite_schema::ServiceInventory;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+/// Trait the rest of the workspace consumes to talk to systemd.
+///
+/// At M1 only [`inventory`](Self::inventory) is implemented. Enable /
+/// disable / mask / restart arrive with M2's apply-engine wiring.
+pub trait Systemd: Send + Sync {
+    /// Snapshot the unit-file states + currently-active units into a
+    /// [`ServiceInventory`].
+    ///
+    /// # Errors
+    /// Implementations propagate adapter-specific failures via
+    /// [`SystemdError`].
+    fn inventory(&self) -> Result<ServiceInventory, SystemdError>;
+}
+
+/// Production [`Systemd`] backed by the `systemctl` binary.
+#[derive(Clone, Debug)]
+pub struct LiveSystemd {
+    binary: PathBuf,
+}
+
+impl LiveSystemd {
+    /// Construct a [`LiveSystemd`] that resolves `systemctl` from `PATH`.
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            binary: PathBuf::from("systemctl"),
+        }
+    }
+
+    /// Construct a [`LiveSystemd`] with a caller-supplied binary path.
+    pub fn with_binary(binary: impl Into<PathBuf>) -> Self {
+        Self {
+            binary: binary.into(),
+        }
+    }
+
+    /// Path of the `systemctl` binary this adapter invokes.
+    #[must_use]
+    pub fn binary(&self) -> &Path {
+        &self.binary
+    }
+
+    fn run(&self, args: &[&str]) -> Result<String, SystemdError> {
+        let output = match Command::new(&self.binary).args(args).output() {
+            Ok(o) => o,
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+                return Err(SystemdError::NotInPath {
+                    hint: "every supported Pearlite host runs systemd; this is unusual",
+                });
+            }
+            Err(e) => return Err(SystemdError::Io(e)),
+        };
+
+        if !output.status.success() {
+            let code = output.status.code().unwrap_or(-1);
+            let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
+            return Err(SystemdError::InvocationFailed { code, stderr });
+        }
+
+        Ok(String::from_utf8(output.stdout)?)
+    }
+}
+
+impl Default for LiveSystemd {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Systemd for LiveSystemd {
+    fn inventory(&self) -> Result<ServiceInventory, SystemdError> {
+        let unit_files = self.run(&["list-unit-files", "--no-pager", "--no-legend"])?;
+        let units = self.run(&[
+            "list-units",
+            "--no-pager",
+            "--no-legend",
+            "--all",
+            "--plain",
+        ])?;
+        Ok(compose_inventory(&unit_files, &units))
+    }
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::expect_used,
+    clippy::unwrap_used,
+    clippy::panic,
+    reason = "tests may use expect()/unwrap()/panic!() per Plan §4.2 + CLAUDE.md"
+)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn systemctl_not_in_path_error_class() {
+        let live = LiveSystemd::with_binary("/nonexistent/path/systemctl-binary-12345");
+        let err = live.inventory().expect_err("must fail");
+        assert!(matches!(err, SystemdError::NotInPath { .. }), "got {err:?}");
+    }
+
+    /// Plan §6.8 acceptance: real systemctl invocation produces a
+    /// well-formed inventory. CI runners are systemd-based; the test
+    /// silent-skips on hosts without systemd.
+    #[test]
+    fn live_systemd_inventory_succeeds_when_systemctl_present() {
+        let live = LiveSystemd::new();
+        let probe = Command::new(live.binary()).arg("--version").output();
+        if !matches!(&probe, Ok(o) if o.status.success()) {
+            return;
+        }
+        let inv = live.inventory().expect("inventory");
+        // Sanity: every unit name ends with a known suffix.
+        for name in inv
+            .enabled
+            .iter()
+            .chain(inv.disabled.iter())
+            .chain(inv.masked.iter())
+        {
+            assert!(
+                name.contains('.'),
+                "unit name without a type suffix: {name}"
+            );
+        }
+    }
+}