runspec-linux-core 0.1.0__tar.gz → 0.2.0__tar.gz

runspec_linux_core-0.2.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# runspec-linux-core Changelog
+
+## [0.2.0] — 2026-06-20
+
+Add package-manager and host-power helpers so a fleet can be patched and
+rebooted through `runspec-linux`.
+
+New in `packages.py` — detect the distro's manager (`apt-get`/`dnf`/`yum`/
+`zypper`/`pacman`) and operate over it:
+
+- `detect_manager()` — first supported manager on PATH (raises
+  `ToolNotFoundError` if none).
+- `list_packages(name_filter=None, limit=100)` — installed packages
+  (name + version), filtered + sorted + capped; `total` is the pre-cap count.
+- `list_upgrades(refresh=True)` — packages with an available upgrade
+  (name/current/candidate). `refresh` updates the index first (needs root);
+  `refresh=False` reads the cache as any user.
+- `upgrade_packages()` — refresh the index and upgrade everything (needs root).
+- `install_package(packages)` / `remove_package(packages)` — install/remove one
+  or more space-separated packages (needs root).
+
+New in `power.py`:
+
+- `reboot_host(delay_minutes=0)` — reboot now or schedule with `shutdown -r +N`,
+  falling back to `systemctl reboot` for an immediate reboot.
+
+Each helper returns plain data and raises `ToolNotFoundError` (no manager/tool)
+or `CommandError` (non-zero exit, e.g. run unprivileged), matching the existing
+contract. Package names are validated against a conservative token shape before
+reaching argv (rejects leading dashes and shell metacharacters), raising
+`ValueError` on a bad name. The write commands run non-interactively
+(`-y`/`--non-interactive`/`--noconfirm`, `DEBIAN_FRONTEND=noninteractive`) and
+return a bounded tail of their output.
+
+## [0.1.0] — 2026-06-09
+
+Initial release.
+
+The pure-Python logic core extracted from `runspec-linux`. Provides the
+system-admin helper functions as plain importable functions — **no dependency on
+`runspec`, no `runspec.toml`, no console-script entry points** — so a package can
+`from runspec_linux_core import nc_send` (and the rest) without surfacing any
+runnables in the venv or in `runspec local` / `runspec serve` discovery.
+
+Each function returns plain data and *raises* on failure (`ToolNotFoundError`
+when a required system tool is absent, `CommandError` when a subprocess reports
+a non-zero exit); the runnable wrappers in `runspec-linux` catch these and render
+the JSON/exit behaviour.
+
+Exports:
+
+- **System** — `system_info`, `disk_usage`, `check_memory`, `list_processes`
+- **Services** — `check_service`, `list_services`, `restart_service`
+- **Logs** — `tail_log`, `search_log`, `journalctl`
+- **Network** — `ping_host`, `check_port`, `show_connections`
+- **Files** — `find_large_files`, `backup_files`
+- **Security** — `last_logins`, `who`
+- **Containers** — `list_containers`, `container_logs`, `restart_container`
+- **TCP** — `nc_send`
+- **Errors** — `LinuxCoreError`, `ToolNotFoundError`, `CommandError`

{runspec_linux_core-0.1.0 → runspec_linux_core-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runspec-linux-core
-Version: 0.1.0
+Version: 0.2.0
 Summary: Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)
 Requires-Python: >=3.10
 Provides-Extra: dev

{runspec_linux_core-0.1.0 → runspec_linux_core-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux-core"
-version = "0.1.0"
+version = "0.2.0"
 requires-python = ">=3.10"
 description = "Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)"
 dependencies = []

{runspec_linux_core-0.1.0 → runspec_linux_core-0.2.0}/runspec_linux_core/__init__.py

@@ -19,6 +19,15 @@ from runspec_linux_core.files import backup_files, find_large_files
 from runspec_linux_core.logs import journalctl, search_log, tail_log
 from runspec_linux_core.nc import nc_send
 from runspec_linux_core.network import check_port, ping_host, show_connections
+from runspec_linux_core.packages import (
+    detect_manager,
+    install_package,
+    list_packages,
+    list_upgrades,
+    remove_package,
+    upgrade_packages,
+)
+from runspec_linux_core.power import reboot_host
 from runspec_linux_core.security import last_logins, who
 from runspec_linux_core.services import check_service, list_services, restart_service
 from runspec_linux_core.system import check_memory, disk_usage, list_processes, system_info
@@ -55,6 +64,15 @@ __all__ = [
     "list_containers",
     "container_logs",
     "restart_container",
+    # packages
+    "detect_manager",
+    "list_packages",
+    "list_upgrades",
+    "upgrade_packages",
+    "install_package",
+    "remove_package",
+    # power
+    "reboot_host",
     # tcp
     "nc_send",
 ]

runspec_linux_core-0.2.0/runspec_linux_core/packages.py

@@ -0,0 +1,289 @@
+"""Package-manager helpers: detect the distro's manager, then list/upgrade/install/remove.
+
+Supports the common Linux families: Debian/Ubuntu (``apt-get`` + ``dpkg``),
+RHEL/Fedora (``dnf``/``yum`` + ``rpm``), SUSE (``zypper`` + ``rpm``), and Arch
+(``pacman``). The read operations (list installed, list upgrades) return plain
+data; the write operations (upgrade, install, remove) need root and raise
+``CommandError`` when the underlying command exits non-zero (for example when
+run as an unprivileged user). ``ToolNotFoundError`` is raised when no supported
+package manager is on PATH.
+"""
+
+import os
+import re
+import shutil
+import subprocess
+
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
+
+# Ordered by preference; the first manager found on PATH wins.
+_MANAGERS = ("apt-get", "dnf", "yum", "zypper", "pacman")
+
+# The argv prefix for each manager's write operations. ``-y`` /
+# ``--non-interactive`` / ``--noconfirm`` keep them unattended (these run over
+# SSH with no TTY). Package names are appended after validation.
+_UPGRADE_CMDS = {
+    "apt-get": ["apt-get", "-y", "upgrade"],
+    "dnf": ["dnf", "-y", "upgrade"],
+    "yum": ["yum", "-y", "update"],
+    "zypper": ["zypper", "--non-interactive", "update"],
+    "pacman": ["pacman", "-Syu", "--noconfirm"],
+}
+_INSTALL_CMDS = {
+    "apt-get": ["apt-get", "install", "-y"],
+    "dnf": ["dnf", "install", "-y"],
+    "yum": ["yum", "install", "-y"],
+    "zypper": ["zypper", "--non-interactive", "install"],
+    "pacman": ["pacman", "-S", "--noconfirm"],
+}
+_REMOVE_CMDS = {
+    "apt-get": ["apt-get", "remove", "-y"],
+    "dnf": ["dnf", "remove", "-y"],
+    "yum": ["yum", "remove", "-y"],
+    "zypper": ["zypper", "--non-interactive", "remove"],
+    "pacman": ["pacman", "-R", "--noconfirm"],
+}
+
+# A conservative package-token shape: starts alphanumeric, then the punctuation
+# real package names use. Rejects whitespace, shell metacharacters, and leading
+# dashes (which a manager would parse as an option) before anything reaches argv.
+_PKG_TOKEN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+:@-]*$")
+
+
+def detect_manager() -> str:
+    """Return the name of the first supported package manager found on PATH.
+
+    Raises ToolNotFoundError if none of apt-get/dnf/yum/zypper/pacman are present.
+    """
+    for mgr in _MANAGERS:
+        if shutil.which(mgr):
+            return mgr
+    raise ToolNotFoundError("No supported package manager found (looked for: " + ", ".join(_MANAGERS) + ")")
+
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess[str]:
+    # DEBIAN_FRONTEND keeps apt from trying to prompt over a non-interactive
+    # SSH channel; it is harmless for the other managers.
+    env = {**os.environ, "DEBIAN_FRONTEND": "noninteractive"}
+    return subprocess.run(cmd, capture_output=True, text=True, env=env)
+
+
+def _tail(output: str, limit: int = 40) -> list[str]:
+    """Return the last ``limit`` non-empty-trimmed lines so payloads stay bounded."""
+    lines = output.strip().splitlines()
+    return lines[-limit:]
+
+
+def _validate_packages(packages: str) -> list[str]:
+    """Split a space-separated package string into validated tokens.
+
+    Raises ValueError if the string is empty or any token is not a plausible
+    package name (this blocks option injection and shell metacharacters before
+    the names reach argv).
+    """
+    names = packages.split()
+    if not names:
+        raise ValueError("no package name given")
+    for name in names:
+        if not _PKG_TOKEN.match(name):
+            raise ValueError(f"invalid package name: {name!r}")
+    return names
+
+
+def list_packages(name_filter: str | None = None, limit: int = 100) -> dict:
+    """Return installed packages (name + version), optionally filtered by substring.
+
+    Read-only. Results are sorted by name and capped at ``limit``; ``total`` is
+    the count before the cap. Raises ToolNotFoundError if no package manager is
+    present, or CommandError if the query command fails.
+    """
+    mgr = detect_manager()
+    if mgr == "apt-get":
+        result = _run(["dpkg-query", "-W", "-f=${Package}\t${Version}\n"])
+        rows = _parse_two_col(result.stdout)
+    elif mgr == "pacman":
+        result = _run(["pacman", "-Q"])
+        rows = _parse_pacman_q(result.stdout)
+    else:  # dnf / yum / zypper are all rpm-based
+        result = _run(["rpm", "-qa", "--qf", "%{NAME}\t%{VERSION}-%{RELEASE}\n"])
+        rows = _parse_two_col(result.stdout)
+
+    if not rows and result.returncode != 0:
+        raise CommandError(result.stderr.strip() or "package query failed")
+
+    if name_filter:
+        needle = name_filter.lower()
+        rows = [r for r in rows if needle in r["name"].lower()]
+    rows.sort(key=lambda r: r["name"])
+    total = len(rows)
+    return {"manager": mgr, "total": total, "count": min(total, limit), "packages": rows[:limit]}
+
+
+def list_upgrades(refresh: bool = True) -> dict:
+    """Return packages with an available upgrade (name, current, candidate).
+
+    When ``refresh`` is true the package index is updated first (this needs root
+    on most systems); pass ``refresh=False`` to read the cached index as any
+    user. Raises ToolNotFoundError if no package manager is present, or
+    CommandError if a refresh or query command fails.
+    """
+    mgr = detect_manager()
+    if mgr == "apt-get":
+        if refresh:
+            _check(_run(["apt-get", "update", "-q"]), "apt-get update")
+        # `apt list --upgradable` reads the cache without root (it warns about an
+        # unstable CLI on stderr, which we ignore).
+        result = _run(["apt", "list", "--upgradable"])
+        upgrades = _parse_apt_list(result.stdout)
+    elif mgr in ("dnf", "yum"):
+        cmd = [mgr, "check-update"]
+        if not refresh:
+            cmd.append("-C")  # cache-only
+        result = _run(cmd)
+        # check-update exits 100 when updates exist, 0 when none — neither is an error.
+        if result.returncode not in (0, 100):
+            raise CommandError(result.stderr.strip() or f"{mgr} check-update failed")
+        upgrades = _parse_dnf_check(result.stdout)
+    elif mgr == "zypper":
+        if refresh:
+            _check(_run(["zypper", "--non-interactive", "refresh"]), "zypper refresh")
+        result = _run(["zypper", "--non-interactive", "list-updates"])
+        upgrades = _parse_zypper_updates(result.stdout)
+    else:  # pacman
+        if refresh:
+            _check(_run(["pacman", "-Sy"]), "pacman -Sy")
+        # `pacman -Qu` exits 1 when there are simply no updates; that is not an error.
+        result = _run(["pacman", "-Qu"])
+        upgrades = _parse_pacman_qu(result.stdout)
+
+    return {"manager": mgr, "refreshed": refresh, "count": len(upgrades), "upgrades": upgrades}
+
+
+def upgrade_packages() -> dict:
+    """Refresh the package index and upgrade all installed packages.
+
+    Needs root. Returns ``{manager, command, upgraded: True, output}`` where
+    ``output`` is a bounded tail of the command's stdout. Raises
+    ToolNotFoundError if no package manager is present, or CommandError if the
+    refresh or upgrade command fails.
+    """
+    mgr = detect_manager()
+    if mgr == "apt-get":
+        _check(_run(["apt-get", "update", "-q"]), "apt-get update")
+    cmd = _UPGRADE_CMDS[mgr]
+    result = _run(cmd)
+    if result.returncode != 0:
+        raise CommandError(result.stderr.strip() or " ".join(cmd) + " failed")
+    return {"manager": mgr, "command": " ".join(cmd), "upgraded": True, "output": _tail(result.stdout)}
+
+
+def install_package(packages: str) -> dict:
+    """Install one or more packages (space-separated). Needs root.
+
+    Returns ``{manager, packages, installed: True, output}``. Raises ValueError
+    on an empty/invalid name, ToolNotFoundError if no package manager is present,
+    or CommandError if the install command fails.
+    """
+    names = _validate_packages(packages)
+    mgr = detect_manager()
+    cmd = [*_INSTALL_CMDS[mgr], *names]
+    result = _run(cmd)
+    if result.returncode != 0:
+        raise CommandError(result.stderr.strip() or " ".join(cmd) + " failed")
+    return {"manager": mgr, "packages": names, "installed": True, "output": _tail(result.stdout)}
+
+
+def remove_package(packages: str) -> dict:
+    """Remove one or more packages (space-separated). Needs root.
+
+    Returns ``{manager, packages, removed: True, output}``. Raises ValueError on
+    an empty/invalid name, ToolNotFoundError if no package manager is present, or
+    CommandError if the remove command fails.
+    """
+    names = _validate_packages(packages)
+    mgr = detect_manager()
+    cmd = [*_REMOVE_CMDS[mgr], *names]
+    result = _run(cmd)
+    if result.returncode != 0:
+        raise CommandError(result.stderr.strip() or " ".join(cmd) + " failed")
+    return {"manager": mgr, "packages": names, "removed": True, "output": _tail(result.stdout)}
+
+
+def _check(result: subprocess.CompletedProcess[str], label: str) -> None:
+    if result.returncode != 0:
+        raise CommandError(result.stderr.strip() or f"{label} failed")
+
+
+def _parse_two_col(output: str) -> list[dict]:
+    """Parse tab-separated ``name<TAB>version`` lines (dpkg-query / rpm output)."""
+    rows = []
+    for line in output.strip().splitlines():
+        if "\t" not in line:
+            continue
+        name, version = line.split("\t", 1)
+        name = name.strip()
+        if name:
+            rows.append({"name": name, "version": version.strip()})
+    return rows
+
+
+def _parse_pacman_q(output: str) -> list[dict]:
+    rows = []
+    for line in output.strip().splitlines():
+        parts = line.split(None, 1)
+        if parts:
+            rows.append({"name": parts[0], "version": parts[1] if len(parts) > 1 else ""})
+    return rows
+
+
+def _parse_apt_list(output: str) -> list[dict]:
+    """Parse ``apt list --upgradable`` lines: ``name/repo candidate arch [upgradable from: current]``."""
+    rows = []
+    for line in output.splitlines():
+        if "/" not in line or "[upgradable from:" not in line:
+            continue
+        name = line.split("/", 1)[0].strip()
+        parts = line.split()
+        candidate = parts[1] if len(parts) > 1 else ""
+        m = re.search(r"\[upgradable from:\s*([^\]]+)\]", line)
+        current = m.group(1).strip() if m else ""
+        rows.append({"name": name, "current": current, "candidate": candidate})
+    return rows
+
+
+def _parse_dnf_check(output: str) -> list[dict]:
+    """Parse ``dnf/yum check-update`` rows: ``name.arch  candidate  repo`` (no current version)."""
+    rows = []
+    for raw in output.splitlines():
+        line = raw.rstrip()
+        if not line or line.startswith(("Last metadata", "Obsoleting", "Security:")):
+            continue
+        parts = line.split()
+        if len(parts) != 3 or "." not in parts[0]:
+            continue
+        name = parts[0].rsplit(".", 1)[0]
+        rows.append({"name": name, "current": "", "candidate": parts[1]})
+    return rows
+
+
+def _parse_zypper_updates(output: str) -> list[dict]:
+    """Parse the ``v |`` rows of ``zypper list-updates`` (pipe-separated columns)."""
+    rows = []
+    for line in output.splitlines():
+        if "|" not in line:
+            continue
+        cols = [c.strip() for c in line.split("|")]
+        if len(cols) < 6 or cols[0] != "v":
+            continue
+        rows.append({"name": cols[2], "current": cols[3], "candidate": cols[4]})
+    return rows
+
+
+def _parse_pacman_qu(output: str) -> list[dict]:
+    """Parse ``pacman -Qu`` lines: ``name current -> candidate``."""
+    rows = []
+    for line in output.strip().splitlines():
+        m = re.match(r"(\S+)\s+(\S+)\s+->\s+(\S+)", line)
+        if m:
+            rows.append({"name": m.group(1), "current": m.group(2), "candidate": m.group(3)})
+    return rows

runspec_linux_core-0.2.0/runspec_linux_core/power.py

@@ -0,0 +1,35 @@
+"""Host power helpers: reboot."""
+
+import shutil
+import subprocess
+
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
+
+
+def reboot_host(delay_minutes: int = 0) -> dict:
+    """Reboot the host, optionally after ``delay_minutes`` minutes. Needs root.
+
+    A delay of 0 (or less) reboots immediately (``shutdown -r now``); a positive
+    delay schedules it (``shutdown -r +N``) and returns straight away. Prefers
+    ``shutdown``, falling back to ``systemctl reboot`` for an immediate reboot if
+    ``shutdown`` is absent. Returns ``{scheduled: True, delay_minutes, command}``.
+
+    Raises ToolNotFoundError if no usable tool is present, or CommandError if the
+    command exits non-zero (for example when run as an unprivileged user).
+    """
+    if shutil.which("shutdown"):
+        when = "now" if delay_minutes <= 0 else f"+{delay_minutes}"
+        cmd = ["shutdown", "-r", when]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise CommandError(result.stderr.strip() or "shutdown failed")
+        return {"scheduled": True, "delay_minutes": max(delay_minutes, 0), "command": " ".join(cmd)}
+
+    # No `shutdown` (unusual). systemctl can only do an immediate reboot.
+    if shutil.which("systemctl") and delay_minutes <= 0:
+        result = subprocess.run(["systemctl", "reboot"], capture_output=True, text=True)
+        if result.returncode != 0:
+            raise CommandError(result.stderr.strip() or "systemctl reboot failed")
+        return {"scheduled": True, "delay_minutes": 0, "command": "systemctl reboot"}
+
+    raise ToolNotFoundError("shutdown not available (and systemctl cannot schedule a delayed reboot)")

runspec_linux_core-0.2.0/tests/test_packages.py

@@ -0,0 +1,137 @@
+"""Package-manager detection, name validation, and output parsing.
+
+The parsers are pure (string in, list of dicts out) so they are tested directly;
+``detect_manager`` and ``list_packages`` are exercised with the subprocess layer
+stubbed so no real package manager is touched.
+"""
+
+import subprocess
+
+import pytest
+
+import runspec_linux_core as core
+from runspec_linux_core import packages as pkg
+from runspec_linux_core.errors import CommandError
+
+
+def _completed(stdout: str = "", returncode: int = 0, stderr: str = "") -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(args=[], returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+# ── detect_manager ────────────────────────────────────────────────────────────
+
+
+def test_detect_manager_prefers_first_found(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Only dnf present (apt-get absent) → dnf wins over later yum/zypper/pacman.
+    monkeypatch.setattr("runspec_linux_core.packages.shutil.which", lambda name: name == "dnf")
+    assert pkg.detect_manager() == "dnf"
+
+
+def test_detect_manager_apt_wins(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.packages.shutil.which", lambda name: name in ("apt-get", "dnf"))
+    assert pkg.detect_manager() == "apt-get"
+
+
+# ── name validation ───────────────────────────────────────────────────────────
+
+
+def test_validate_packages_splits_multiple() -> None:
+    assert pkg._validate_packages("htop  vim curl") == ["htop", "vim", "curl"]
+
+
+def test_validate_packages_allows_real_names() -> None:
+    assert pkg._validate_packages("g++ lib32z1 python3.10 foo:amd64") == [
+        "g++",
+        "lib32z1",
+        "python3.10",
+        "foo:amd64",
+    ]
+
+
+def test_validate_packages_rejects_empty() -> None:
+    with pytest.raises(ValueError):
+        pkg._validate_packages("   ")
+
+
+@pytest.mark.parametrize("bad", ["-rf", "foo;rm", "$(whoami)", "a b&"])
+def test_validate_packages_rejects_injection(bad: str) -> None:
+    # The "a b&" case splits into ["a", "b&"]; the "b&" token must be rejected.
+    with pytest.raises(ValueError):
+        pkg._validate_packages(bad)
+
+
+# ── parsers ───────────────────────────────────────────────────────────────────
+
+
+def test_parse_two_col() -> None:
+    out = "htop\t3.0.5-7\nvim\t2:8.2\nbroken-line-no-tab\n"
+    assert pkg._parse_two_col(out) == [
+        {"name": "htop", "version": "3.0.5-7"},
+        {"name": "vim", "version": "2:8.2"},
+    ]
+
+
+def test_parse_pacman_q() -> None:
+    assert pkg._parse_pacman_q("htop 3.0.5-1\nvim 8.2.0-1\n") == [
+        {"name": "htop", "version": "3.0.5-1"},
+        {"name": "vim", "version": "8.2.0-1"},
+    ]
+
+
+def test_parse_apt_list() -> None:
+    out = "Listing...\nhtop/focal-updates 3.0.5-1 amd64 [upgradable from: 2.2.0-2]\nvim/focal 2:8.2 amd64 [upgradable from: 2:8.1]\n"
+    assert pkg._parse_apt_list(out) == [
+        {"name": "htop", "current": "2.2.0-2", "candidate": "3.0.5-1"},
+        {"name": "vim", "current": "2:8.1", "candidate": "2:8.2"},
+    ]
+
+
+def test_parse_dnf_check() -> None:
+    out = "Last metadata expiration check: 0:01 ago.\n\nhttpd.x86_64    2.4.53-7.el9    appstream\nkernel.x86_64   5.14.0-70       baseos\n"
+    assert pkg._parse_dnf_check(out) == [
+        {"name": "httpd", "current": "", "candidate": "2.4.53-7.el9"},
+        {"name": "kernel", "current": "", "candidate": "5.14.0-70"},
+    ]
+
+
+def test_parse_zypper_updates() -> None:
+    out = (
+        "S | Repository | Name | Current Version | Available Version | Arch\n"
+        "--+------------+------+-----------------+-------------------+------\n"
+        "v | repo-oss   | curl | 7.79.1-1        | 7.79.1-2          | x86_64\n"
+    )
+    assert pkg._parse_zypper_updates(out) == [
+        {"name": "curl", "current": "7.79.1-1", "candidate": "7.79.1-2"},
+    ]
+
+
+def test_parse_pacman_qu() -> None:
+    out = "htop 3.0.5-1 -> 3.1.0-1\nvim 8.2.0-1 -> 8.2.1-1\n"
+    assert pkg._parse_pacman_qu(out) == [
+        {"name": "htop", "current": "3.0.5-1", "candidate": "3.1.0-1"},
+        {"name": "vim", "current": "8.2.0-1", "candidate": "8.2.1-1"},
+    ]
+
+
+# ── list_packages (filter + limit + sort) ─────────────────────────────────────
+
+
+def test_list_packages_filters_sorts_and_caps(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(pkg, "detect_manager", lambda: "apt-get")
+    monkeypatch.setattr(
+        pkg,
+        "_run",
+        lambda cmd: _completed("vim\t2\nlibvirt\t8\nhtop\t3\nzlib\t1\n"),
+    )
+    result = core.list_packages(name_filter="li", limit=1)
+    assert result["manager"] == "apt-get"
+    assert result["total"] == 2  # libvirt, zlib both contain "li"
+    assert result["count"] == 1
+    assert result["packages"] == [{"name": "libvirt", "version": "8"}]  # sorted, capped
+
+
+def test_list_packages_raises_on_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(pkg, "detect_manager", lambda: "apt-get")
+    monkeypatch.setattr(pkg, "_run", lambda cmd: _completed("", returncode=2, stderr="boom"))
+    with pytest.raises(CommandError):
+        core.list_packages()

runspec_linux_core-0.2.0/tests/test_power.py

@@ -0,0 +1,58 @@
+"""reboot_host builds the right command and surfaces failures as CommandError."""
+
+import subprocess
+
+import pytest
+
+from runspec_linux_core import power
+from runspec_linux_core.errors import CommandError
+
+
+def _completed(returncode: int = 0, stderr: str = "") -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(args=[], returncode=returncode, stdout="", stderr=stderr)
+
+
+def test_reboot_now_uses_shutdown(monkeypatch: pytest.MonkeyPatch) -> None:
+    seen: list[list[str]] = []
+    monkeypatch.setattr("runspec_linux_core.power.shutil.which", lambda name: name == "shutdown")
+    monkeypatch.setattr(
+        "runspec_linux_core.power.subprocess.run",
+        lambda cmd, **kw: seen.append(cmd) or _completed(),
+    )
+    result = power.reboot_host(0)
+    assert seen == [["shutdown", "-r", "now"]]
+    assert result == {"scheduled": True, "delay_minutes": 0, "command": "shutdown -r now"}
+
+
+def test_reboot_with_delay_schedules(monkeypatch: pytest.MonkeyPatch) -> None:
+    seen: list[list[str]] = []
+    monkeypatch.setattr("runspec_linux_core.power.shutil.which", lambda name: name == "shutdown")
+    monkeypatch.setattr(
+        "runspec_linux_core.power.subprocess.run",
+        lambda cmd, **kw: seen.append(cmd) or _completed(),
+    )
+    result = power.reboot_host(5)
+    assert seen == [["shutdown", "-r", "+5"]]
+    assert result["delay_minutes"] == 5
+
+
+def test_reboot_falls_back_to_systemctl(monkeypatch: pytest.MonkeyPatch) -> None:
+    seen: list[list[str]] = []
+    monkeypatch.setattr("runspec_linux_core.power.shutil.which", lambda name: name == "systemctl")
+    monkeypatch.setattr(
+        "runspec_linux_core.power.subprocess.run",
+        lambda cmd, **kw: seen.append(cmd) or _completed(),
+    )
+    result = power.reboot_host(0)
+    assert seen == [["systemctl", "reboot"]]
+    assert result["command"] == "systemctl reboot"
+
+
+def test_reboot_non_zero_raises(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.power.shutil.which", lambda name: name == "shutdown")
+    monkeypatch.setattr(
+        "runspec_linux_core.power.subprocess.run",
+        lambda cmd, **kw: _completed(returncode=1, stderr="Operation not permitted"),
+    )
+    with pytest.raises(CommandError):
+        power.reboot_host(0)

{runspec_linux_core-0.1.0 → runspec_linux_core-0.2.0}/tests/test_preconditions.py

@@ -68,3 +68,39 @@ def test_restart_container_requires_docker(monkeypatch: pytest.MonkeyPatch) -> N
     monkeypatch.setattr("runspec_linux_core.containers.shutil.which", lambda _: None)
     with pytest.raises(ToolNotFoundError):
         core.restart_container("web")
+
+
+def test_list_packages_requires_a_manager(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.packages.shutil.which", lambda _: None)
+    with pytest.raises(ToolNotFoundError):
+        core.list_packages()
+
+
+def test_list_upgrades_requires_a_manager(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.packages.shutil.which", lambda _: None)
+    with pytest.raises(ToolNotFoundError):
+        core.list_upgrades()
+
+
+def test_upgrade_packages_requires_a_manager(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.packages.shutil.which", lambda _: None)
+    with pytest.raises(ToolNotFoundError):
+        core.upgrade_packages()
+
+
+def test_install_package_requires_a_manager(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.packages.shutil.which", lambda _: None)
+    with pytest.raises(ToolNotFoundError):
+        core.install_package("htop")
+
+
+def test_remove_package_requires_a_manager(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.packages.shutil.which", lambda _: None)
+    with pytest.raises(ToolNotFoundError):
+        core.remove_package("htop")
+
+
+def test_reboot_host_requires_a_tool(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.power.shutil.which", lambda _: None)
+    with pytest.raises(ToolNotFoundError):
+        core.reboot_host()

runspec_linux_core-0.1.0/CHANGELOG.md

@@ -1,28 +0,0 @@
-# runspec-linux-core Changelog
-
-## [0.1.0] — 2026-06-09
-
-Initial release.
-
-The pure-Python logic core extracted from `runspec-linux`. Provides the
-system-admin helper functions as plain importable functions — **no dependency on
-`runspec`, no `runspec.toml`, no console-script entry points** — so a package can
-`from runspec_linux_core import nc_send` (and the rest) without surfacing any
-runnables in the venv or in `runspec local` / `runspec serve` discovery.
-
-Each function returns plain data and *raises* on failure (`ToolNotFoundError`
-when a required system tool is absent, `CommandError` when a subprocess reports
-a non-zero exit); the runnable wrappers in `runspec-linux` catch these and render
-the JSON/exit behaviour.
-
-Exports:
-
-- **System** — `system_info`, `disk_usage`, `check_memory`, `list_processes`
-- **Services** — `check_service`, `list_services`, `restart_service`
-- **Logs** — `tail_log`, `search_log`, `journalctl`
-- **Network** — `ping_host`, `check_port`, `show_connections`
-- **Files** — `find_large_files`, `backup_files`
-- **Security** — `last_logins`, `who`
-- **Containers** — `list_containers`, `container_logs`, `restart_container`
-- **TCP** — `nc_send`
-- **Errors** — `LinuxCoreError`, `ToolNotFoundError`, `CommandError`