WP-10: OS and package inventory

Debian inspector (dpkg-query, apt-get -s upgrade, snap list, os-release,
reboot-required) behind a CommandRunner port with tested parsers, fake
inspector for dev, persisted inventory snapshot, package_refresh job,
/api/system/inventory, Updates page with OS card, summary and filterable
package table.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

backend/crates/api/src/lib.rs

@@ -7,18 +7,24 @@ pub mod jobs;
 pub mod openapi;
 pub mod rate_limit;
 pub mod settings;
+pub mod system;
 pub mod test_support;
 pub mod users;
 
 use std::sync::Arc;
 
 use application::scheduler::Scheduler;
-use application::{AuthService, JobRunner, SettingsService, UserService};
+use application::{
+    AuthService, InventoryService, JobRunner, PackageRefreshJob, SettingsService, UserService,
+};
 use axum::{routing::get, Json, Router};
+use domain::jobs::JobKind;
+use domain::ports::HostInspector;
 use domain::ports::Mailer;
 use infrastructure::{
-    AesGcmCipher, Argon2Hasher, DbPool, JwtIssuer, LettreMailer, SqliteAuditLog, SqliteJobRuns,
-    SqliteRefreshTokens, SqliteSettings, SqliteUsers,
+    AesGcmCipher, Argon2Hasher, DbPool, DebianInspector, FakeHostInspector, JwtIssuer,
+    LettreMailer, SqliteAuditLog, SqliteInventory, SqliteJobRuns, SqliteRefreshTokens,
+    SqliteSettings, SqliteUsers, SystemCommandRunner,
 };
 use tower_http::services::{ServeDir, ServeFile};
 use tower_http::trace::TraceLayer;
@@ -32,20 +38,19 @@ pub struct AppState {
     pub users: Arc<UserService>,
     pub settings: Arc<SettingsService>,
     pub jobs: Arc<JobRunner>,
+    pub inventory: Arc<InventoryService>,
     pub login_limiter: Arc<rate_limit::RateLimiter>,
 }
 
 impl AppState {
     /// Wire the services on top of a connected database.
     pub fn new(cfg: Config, pool: DbPool) -> anyhow::Result<Self> {
-        let fake = cfg.fake_host;
-        Self::with_adapters(cfg, pool, Arc::new(LettreMailer), move |r| {
-            if fake {
-                test_support::register_test_jobs(r)
-            } else {
-                r
-            }
-        })
+        let inspector: Arc<dyn HostInspector> = if cfg.fake_host {
+            Arc::new(FakeHostInspector)
+        } else {
+            Arc::new(DebianInspector::new(Arc::new(SystemCommandRunner)))
+        };
+        Self::with_adapters(cfg, pool, Arc::new(LettreMailer), inspector, |r| r)
     }
 
     /// Wiring with replaceable adapters (used by tests and the fake-host mode).
@@ -53,6 +58,7 @@ impl AppState {
         cfg: Config,
         pool: DbPool,
         mailer: Arc<dyn Mailer>,
+        inspector: Arc<dyn HostInspector>,
         register_jobs: impl FnOnce(JobRunner) -> JobRunner,
     ) -> anyhow::Result<Self> {
         let users = Arc::new(SqliteUsers(pool.clone()));
@@ -70,13 +76,22 @@ impl AppState {
             cipher,
             mailer,
         ));
-        let jobs = Arc::new(register_jobs(JobRunner::new(Arc::new(SqliteJobRuns(pool)))));
+        let inventory = Arc::new(InventoryService::new(
+            inspector,
+            Arc::new(SqliteInventory(pool.clone())),
+        ));
+        let runner = JobRunner::new(Arc::new(SqliteJobRuns(pool))).register(
+            JobKind::PackageRefresh,
+            Arc::new(PackageRefreshJob(inventory.clone())),
+        );
+        let jobs = Arc::new(register_jobs(runner));
         Ok(Self {
             cfg,
             auth: Arc::new(auth),
             users: Arc::new(UserService::new(users, hasher)),
             settings,
             jobs,
+            inventory,
             login_limiter: Arc::new(rate_limit::RateLimiter::new(
                 10,
                 std::time::Duration::from_secs(60),
@@ -109,6 +124,7 @@ pub fn build_app(state: AppState) -> Router {
         .nest("/api/users", users::router())
         .nest("/api/settings", settings::router())
         .nest("/api/jobs", jobs::router())
+        .nest("/api/system", system::router())
         .fallback_service(spa)
         .layer(TraceLayer::new_for_http())
         .with_state(state)

backend/crates/api/src/openapi.rs

@@ -26,6 +26,7 @@ impl Modify for BearerAuth {
         crate::users::list, crate::users::create, crate::users::get_one, crate::users::update, crate::users::reset_password,
         crate::settings::get_smtp, crate::settings::put_smtp, crate::settings::test_smtp, crate::settings::list_schedules, crate::settings::put_schedule,
         crate::jobs::list, crate::jobs::kinds, crate::jobs::get_one, crate::jobs::run,
+        crate::system::inventory,
     ),
     modifiers(&BearerAuth)
 )]

backend/crates/api/src/system.rs

@@ -0,0 +1,62 @@
+//! /api/system: host inventory.
+use axum::extract::State;
+use axum::routing::get;
+use axum::{Json, Router};
+use domain::host::{OsInfo, Package};
+use serde::Serialize;
+use utoipa::ToSchema;
+
+use crate::error::ApiError;
+use crate::extract::AuthUser;
+use crate::AppState;
+
+pub fn router() -> Router<AppState> {
+    Router::new().route("/inventory", get(inventory))
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct Summary {
+    pub total: usize,
+    pub upgradable: usize,
+    pub security: usize,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct InventoryResponse {
+    pub refreshed_at: Option<chrono::DateTime<chrono::Utc>>,
+    #[schema(value_type = Object)]
+    pub os: Option<OsInfo>,
+    #[schema(value_type = Vec<Object>)]
+    pub packages: Vec<Package>,
+    pub summary: Summary,
+}
+
+#[utoipa::path(get, path = "/api/system/inventory", tag = "system", security(("bearer" = [])), responses((status = 200, body = InventoryResponse)))]
+async fn inventory(
+    State(state): State<AppState>,
+    _: AuthUser,
+) -> Result<Json<InventoryResponse>, ApiError> {
+    let res = match state.inventory.current().await? {
+        Some(inv) => InventoryResponse {
+            summary: Summary {
+                total: inv.packages.len(),
+                upgradable: inv.upgradable(),
+                security: inv.security_upgrades(),
+            },
+            refreshed_at: Some(inv.refreshed_at),
+            os: Some(inv.os),
+            packages: inv.packages,
+        },
+        None => InventoryResponse {
+            refreshed_at: None,
+            os: None,
+            packages: vec![],
+            summary: Summary {
+                total: 0,
+                upgradable: 0,
+                security: 0,
+            },
+        },
+    };
+    Ok(Json(res))
+}

backend/crates/api/src/test_support.rs

@@ -4,7 +4,6 @@ use std::sync::{Arc, Mutex};
 use application::{JobHandler, JobLog, JobRunner};
 use async_trait::async_trait;
 use axum::Router;
-use domain::jobs::JobKind;
 use domain::ports::Mailer;
 use domain::settings::SmtpSettings;
 use domain::DomainError;
@@ -49,6 +48,7 @@ pub fn sent_mails(_app: &Router) -> Vec<(Vec<String>, String, String)> {
     SENT.lock().unwrap().clone()
 }
 
+/// Test handler for kinds without a real implementation yet.
 pub struct TestJob;
 
 #[async_trait]
@@ -60,7 +60,7 @@ impl JobHandler for TestJob {
 }
 
 pub fn register_test_jobs(runner: JobRunner) -> JobRunner {
-    runner.register(JobKind::PackageRefresh, Arc::new(TestJob))
+    runner
 }
 
 pub async fn build_test_app() -> Router {
@@ -79,8 +79,14 @@ async fn build_test_app_with(cfg: Config) -> Router {
     let pool = infrastructure::connect(&cfg.database_url)
         .await
         .expect("db");
-    let state = AppState::with_adapters(cfg, pool, Arc::new(RecordingMailer), register_test_jobs)
-        .expect("state");
+    let state = AppState::with_adapters(
+        cfg,
+        pool,
+        Arc::new(RecordingMailer),
+        Arc::new(infrastructure::FakeHostInspector),
+        register_test_jobs,
+    )
+    .expect("state");
     state.bootstrap().await.expect("bootstrap");
     build_app(state)
 }

backend/crates/api/tests/jobs.rs

@@ -31,10 +31,7 @@ async fn admin_runs_a_job_and_sees_it_in_the_list_with_log() {
         let run = get(&app, &format!("/api/jobs/{id}"), Some(&token)).await;
         status = run.json["status"].as_str().unwrap().to_string();
         if status != "running" {
-            assert!(run.json["log"]
-                .as_str()
-                .unwrap()
-                .contains("test handler ran"));
+            assert!(run.json["log"].as_str().unwrap().contains("packages"));
             break;
         }
         tokio::time::sleep(std::time::Duration::from_millis(20)).await;

backend/crates/application/src/inventory_service.rs

@@ -1,6 +1,7 @@
 use std::sync::Arc;
 
 use async_trait::async_trait;
+use chrono::Utc;
 use domain::host::Inventory;
 use domain::ports::{HostInspector, InventoryRepository};
 use domain::DomainError;
@@ -14,18 +15,26 @@ pub struct InventoryService {
 
 impl InventoryService {
     pub fn new(inspector: Arc<dyn HostInspector>, repo: Arc<dyn InventoryRepository>) -> Self {
-        let _ = (&inspector, &repo);
         Self { inspector, repo }
     }
 
     /// Query the host and persist a new snapshot.
     pub async fn refresh(&self) -> Result<Inventory, DomainError> {
-        todo!()
+        let os = self.inspector.os_info().await?;
+        let mut packages = self.inspector.packages().await?;
+        packages.sort_by(|a, b| a.name.cmp(&b.name));
+        let inventory = Inventory {
+            os,
+            packages,
+            refreshed_at: Utc::now(),
+        };
+        self.repo.save(&inventory).await?;
+        Ok(inventory)
     }
 
     /// Last persisted snapshot.
     pub async fn current(&self) -> Result<Option<Inventory>, DomainError> {
-        todo!()
+        self.repo.load().await
     }
 }
 
@@ -34,7 +43,27 @@ pub struct PackageRefreshJob(pub Arc<InventoryService>);
 
 #[async_trait]
 impl JobHandler for PackageRefreshJob {
-    async fn run(&self, _params: Option<String>, _log: &dyn JobLog) -> Result<(), String> {
-        todo!()
+    async fn run(&self, _params: Option<String>, log: &dyn JobLog) -> Result<(), String> {
+        log.line("querying host for OS and package information")
+            .await;
+        let inv = self.0.refresh().await.map_err(|e| e.to_string())?;
+        log.line(&format!(
+            "{} {} on kernel {}",
+            inv.os.name, inv.os.version, inv.os.kernel
+        ))
+        .await;
+        log.line(&format!(
+            "{} packages, {} upgradable ({} security){}",
+            inv.packages.len(),
+            inv.upgradable(),
+            inv.security_upgrades(),
+            if inv.os.reboot_required {
+                ", reboot required"
+            } else {
+                ""
+            }
+        ))
+        .await;
+        Ok(())
     }
 }

backend/crates/infrastructure/src/host/debian.rs

@@ -2,7 +2,7 @@
 use std::sync::Arc;
 
 use async_trait::async_trait;
-use domain::host::{OsInfo, Package};
+use domain::host::{OsInfo, Package, PackageSource};
 use domain::ports::HostInspector;
 use domain::DomainError;
 
@@ -21,32 +21,134 @@ impl DebianInspector {
 #[async_trait]
 impl HostInspector for DebianInspector {
     async fn os_info(&self) -> Result<OsInfo, DomainError> {
-        todo!()
+        let r = &self.runner;
+        let (name, version) =
+            parse_os_release(&r.read_file("/etc/os-release").await?.unwrap_or_default());
+        let uptime_secs = r
+            .read_file("/proc/uptime")
+            .await?
+            .and_then(|s| s.split_whitespace().next()?.parse::<f64>().ok())
+            .unwrap_or(0.0) as u64;
+        Ok(OsInfo {
+            hostname: r.run("hostname", &[]).await?.stdout.trim().to_string(),
+            name,
+            version,
+            kernel: r.run("uname", &["-r"]).await?.stdout.trim().to_string(),
+            uptime_secs,
+            reboot_required: r.read_file("/var/run/reboot-required").await?.is_some(),
+        })
     }
 
     async fn packages(&self) -> Result<Vec<Package>, DomainError> {
-        todo!()
+        let r = &self.runner;
+        let dpkg = r
+            .run(
+                "dpkg-query",
+                &["-W", "-f", "${Package}\t${Version}\t${Status}\n"],
+            )
+            .await?;
+        if !dpkg.success {
+            return Err(DomainError::Unavailable(format!(
+                "dpkg-query failed: {}",
+                dpkg.stderr.trim()
+            )));
+        }
+        // refresh the package index first; a failure here is logged but not fatal
+        let _ = r.run("apt-get", &["update", "-q"]).await;
+        let sim = r
+            .run(
+                "apt-get",
+                &[
+                    "-s",
+                    "--with-new-pkgs",
+                    "-o",
+                    "Debug::NoLocking=1",
+                    "upgrade",
+                ],
+            )
+            .await?;
+        let upgrades: std::collections::HashMap<String, (String, bool)> =
+            parse_apt_simulation(&sim.stdout)
+                .into_iter()
+                .map(|(n, v, s)| (n, (v, s)))
+                .collect();
+        let mut packages: Vec<Package> = parse_dpkg(&dpkg.stdout)
+            .into_iter()
+            .map(|(name, installed)| {
+                let up = upgrades.get(&name);
+                Package {
+                    candidate: up.map(|(v, _)| v.clone()),
+                    is_security: up.is_some_and(|(_, s)| *s),
+                    name,
+                    source: PackageSource::Apt,
+                    installed,
+                }
+            })
+            .collect();
+        if let Ok(snap) = r.run("snap", &["list"]).await {
+            packages.extend(
+                parse_snap_list(&snap.stdout)
+                    .into_iter()
+                    .map(|(name, installed)| Package {
+                        name,
+                        source: PackageSource::Snap,
+                        installed,
+                        candidate: None,
+                        is_security: false,
+                    }),
+            );
+        }
+        Ok(packages)
     }
 }
 
 /// `dpkg-query -W -f '${Package}\t${Version}\t${Status}\n'` → (name, version) of installed packages.
-pub fn parse_dpkg(_out: &str) -> Vec<(String, String)> {
-    todo!()
+pub fn parse_dpkg(out: &str) -> Vec<(String, String)> {
+    out.lines()
+        .filter_map(|l| {
+            let mut it = l.split('\t');
+            let (name, version, status) = (it.next()?, it.next()?, it.next()?);
+            (status.trim() == "install ok installed")
+                .then(|| (name.to_string(), version.to_string()))
+        })
+        .collect()
 }
 
 /// `apt-get -s upgrade` → (name, candidate version, is_security) for lines starting with `Inst`.
-pub fn parse_apt_simulation(_out: &str) -> Vec<(String, String, bool)> {
-    todo!()
+pub fn parse_apt_simulation(out: &str) -> Vec<(String, String, bool)> {
+    out.lines()
+        .filter_map(|l| {
+            let rest = l.strip_prefix("Inst ")?;
+            let name = rest.split_whitespace().next()?;
+            let paren = &rest[rest.find('(')? + 1..];
+            let version = paren.split_whitespace().next()?;
+            let is_security = paren.to_ascii_lowercase().contains("security");
+            Some((name.to_string(), version.to_string(), is_security))
+        })
+        .collect()
 }
 
 /// `snap list` → (name, version) skipping the header.
-pub fn parse_snap_list(_out: &str) -> Vec<(String, String)> {
-    todo!()
+pub fn parse_snap_list(out: &str) -> Vec<(String, String)> {
+    out.lines()
+        .skip(1)
+        .filter_map(|l| {
+            let mut it = l.split_whitespace();
+            Some((it.next()?.to_string(), it.next()?.to_string()))
+        })
+        .collect()
 }
 
 /// `/etc/os-release` → (PRETTY_NAME, VERSION_ID).
-pub fn parse_os_release(_content: &str) -> (String, String) {
-    todo!()
+pub fn parse_os_release(content: &str) -> (String, String) {
+    let get = |key: &str| {
+        content
+            .lines()
+            .find_map(|l| l.strip_prefix(key)?.strip_prefix('='))
+            .map(|v| v.trim().trim_matches('"').to_string())
+            .unwrap_or_default()
+    };
+    (get("PRETTY_NAME"), get("VERSION_ID"))
 }
 
 #[cfg(test)]