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

runspec_linux_core-0.3.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# runspec-linux-core Changelog
+
+## [0.3.0] — 2026-06-20
+
+Add `enable_passwordless_sudo()` (new `sudoers.py`) — the one-time bootstrap that
+makes the `run_as = "root"` package/power runnables work without a password.
+
+- Installs a validated drop-in at `/etc/sudoers.d/runspec`. Two scopes:
+  `"scoped"` → `NOPASSWD` for the runspec venv's runnable scripts only
+  (`{venv_bin}/`); `"all"` → `NOPASSWD: ALL`.
+- The sudo password is read from **stdin via `sudo -S`** — never on argv, in the
+  process table, shell history, or the audit log.
+- Validates with `visudo -cf` before install *and* `visudo -c` after; rolls the
+  drop-in back if the post-install check fails, so a typo can't lock sudo out.
+- The target user name is validated against a strict pattern before it reaches
+  the file (no rule injection); idempotent when an identical drop-in exists.
+- Raises `ValueError` (bad scope/user), `ToolNotFoundError` (no `sudo`/`visudo`),
+  or `CommandError` (auth failure / validation failure).
+
+Note: the console's *agent* path wraps the command in `env(1)`, so a `"scoped"`
+grant covers manual/CLI runs; agent-driven runs need `"all"`.
+
+## [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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runspec-linux-core
-Version: 0.1.0
+Version: 0.3.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.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux-core"
-version = "0.1.0"
+version = "0.3.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.3.0}/runspec_linux_core/__init__.py

@@ -19,8 +19,18 @@ 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.sudoers import enable_passwordless_sudo
 from runspec_linux_core.system import check_memory, disk_usage, list_processes, system_info
 
 __all__ = [
@@ -55,6 +65,17 @@ __all__ = [
     "list_containers",
     "container_logs",
     "restart_container",
+    # packages
+    "detect_manager",
+    "list_packages",
+    "list_upgrades",
+    "upgrade_packages",
+    "install_package",
+    "remove_package",
+    # power
+    "reboot_host",
+    # sudoers
+    "enable_passwordless_sudo",
     # tcp
     "nc_send",
 ]

runspec_linux_core-0.3.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.3.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.3.0/runspec_linux_core/sudoers.py

@@ -0,0 +1,129 @@
+"""Bootstrap passwordless sudo so the console's ``run_as = "root"`` path works.
+
+This is the one-time, interactive complement to ``run_as``: the operator supplies
+their sudo password (delivered out of band by the caller — never on argv) and we
+install a **validated** drop-in under ``/etc/sudoers.d`` so subsequent
+``run_as = "root"`` invocations escalate without a password.
+
+The password is read from stdin via ``sudo -S`` — it never appears in argv, the
+process table, shell history, or the audit log. The drop-in is validated with
+``visudo`` before *and* after install, and rolled back if the post-install check
+fails, so a typo can't lock the operator out of sudo.
+
+Two grant scopes:
+
+- ``"scoped"`` — ``NOPASSWD`` only for the runspec venv's runnable scripts
+  (``{venv_bin}/``). Least privilege, and enough for **manual** console runs and
+  direct CLI/cron. Note: the console's *agent* path wraps the command in
+  ``env(1)`` to carry ``RUNSPEC_AGENT`` through sudo, so under the agent the
+  command sudo sees is ``/usr/bin/env …`` — which this scope does **not** match.
+  Agent-driven fleet management therefore needs ``"all"``.
+- ``"all"`` — ``NOPASSWD: ALL``. Works for every path (manual *and* agent).
+"""
+
+import getpass
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
+
+_DROP_IN = "/etc/sudoers.d/runspec"
+_MANAGED_HEADER = "# Managed by runspec-linux enable-passwordless-sudo\n"
+
+# POSIX-ish user/group name: starts with a letter or underscore, then letters,
+# digits, _, -, . and an optional trailing $ (machine accounts). Validated before
+# interpolation into the sudoers file so a crafted name can't inject extra rules.
+_USER_RE = re.compile(r"^[a-z_][a-z0-9_.-]*\$?$")
+
+
+def _runspec_bin_dir() -> str:
+    """The venv bin directory holding the runspec runnable scripts.
+
+    The console invokes a runnable as ``{bin_dir}/{runnable}``; on a standard
+    venv install that is the directory of the running interpreter (kept as the
+    venv path, not resolved through symlinks).
+    """
+    return os.path.dirname(sys.executable)
+
+
+def _sudoers_content(user: str, scope: str, bin_dir: str) -> str:
+    # scoped: a trailing slash matches any command in the runspec venv bin dir.
+    rule = f"{user} ALL=(ALL) NOPASSWD: ALL" if scope == "all" else f"{user} ALL=(root) NOPASSWD: {bin_dir}/"
+    return f"{_MANAGED_HEADER}{rule}\n"
+
+
+def _sudo(password: str, argv: list[str]) -> subprocess.CompletedProcess:
+    """Run ``sudo -S -p '' argv``, feeding ``password`` on stdin (never on argv)."""
+    return subprocess.run(
+        ["sudo", "-S", "-p", "", *argv],
+        input=password + "\n",
+        capture_output=True,
+        text=True,
+    )
+
+
+def _auth_hint(result: subprocess.CompletedProcess) -> str:
+    err = result.stderr.strip()
+    low = err.lower()
+    if "incorrect password" in low or "try again" in low or "authentication failure" in low:
+        return "sudo authentication failed — check the password"
+    return err or "sudo command failed"
+
+
+def enable_passwordless_sudo(password: str, user: str | None = None, scope: str = "scoped") -> dict:
+    """Install a validated ``/etc/sudoers.d/runspec`` granting passwordless sudo.
+
+    ``user`` defaults to the current login user. ``scope`` is ``"scoped"`` (the
+    runspec venv runnables only) or ``"all"`` (``NOPASSWD: ALL``). Returns
+    ``{user, scope, path, installed: True, already_configured}``.
+
+    Raises ValueError on a bad scope/user, ToolNotFoundError if sudo/visudo are
+    missing, or CommandError on a sudo auth failure or a sudoers validation
+    failure (in which case the drop-in is rolled back).
+    """
+    if scope not in ("scoped", "all"):
+        raise ValueError(f"invalid scope: {scope!r} (expected 'scoped' or 'all')")
+    user = user or getpass.getuser()
+    if not _USER_RE.match(user):
+        raise ValueError(f"invalid user name: {user!r}")
+    if not shutil.which("sudo"):
+        raise ToolNotFoundError("sudo is not installed")
+    if not shutil.which("visudo"):
+        raise ToolNotFoundError("visudo is not installed (needed to validate the sudoers file)")
+
+    content = _sudoers_content(user, scope, _runspec_bin_dir())
+
+    with tempfile.NamedTemporaryFile("w", suffix=".sudoers", delete=False) as tf:
+        tf.write(content)
+        tmp_path = tf.name
+    try:
+        # 1) Validate the generated syntax locally before touching the system.
+        check = subprocess.run(["visudo", "-cf", tmp_path], capture_output=True, text=True)
+        if check.returncode != 0:
+            detail = check.stdout.strip() or check.stderr.strip()
+            raise CommandError(f"generated sudoers failed validation: {detail}")
+
+        # 2) Idempotent: identical drop-in already present? (reading it needs root)
+        existing = _sudo(password, ["cat", _DROP_IN])
+        if existing.returncode == 0 and existing.stdout == content:
+            return {"user": user, "scope": scope, "path": _DROP_IN, "installed": True, "already_configured": True}
+
+        # 3) Install atomically as root, 0440 root:root.
+        install = _sudo(password, ["install", "-m", "0440", "-o", "root", "-g", "root", tmp_path, _DROP_IN])
+        if install.returncode != 0:
+            raise CommandError(_auth_hint(install))
+
+        # 4) Re-validate the whole sudoers tree; roll our drop-in back if broken.
+        verify = _sudo(password, ["visudo", "-c"])
+        if verify.returncode != 0:
+            _sudo(password, ["rm", "-f", _DROP_IN])
+            detail = verify.stdout.strip() or verify.stderr.strip()
+            raise CommandError(f"sudoers validation failed after install — rolled back: {detail}")
+
+        return {"user": user, "scope": scope, "path": _DROP_IN, "installed": True, "already_configured": False}
+    finally:
+        os.unlink(tmp_path)

runspec_linux_core-0.3.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.3.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.3.0}/tests/test_preconditions.py

@@ -68,3 +68,45 @@ 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()
+
+
+def test_enable_passwordless_sudo_requires_sudo(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.sudoers.shutil.which", lambda _: None)
+    with pytest.raises(ToolNotFoundError):
+        core.enable_passwordless_sudo("pw", "alice", "scoped")

runspec_linux_core-0.3.0/tests/test_sudoers.py

@@ -0,0 +1,147 @@
+"""enable_passwordless_sudo: content generation, validation, install + rollback.
+
+No real sudo/visudo is invoked — the subprocess layer is stubbed so the control
+flow (pre-validate, idempotency, install, post-validate, rollback) is exercised
+deterministically. The password is asserted to travel via stdin, never argv.
+"""
+
+import subprocess
+
+import pytest
+
+from runspec_linux_core import sudoers
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
+
+
+def _ok(stdout: str = "", returncode: int = 0, stderr: str = "") -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(args=[], returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+@pytest.fixture(autouse=True)
+def _tools_present(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.sudoers.shutil.which", lambda name: f"/usr/sbin/{name}")
+    monkeypatch.setattr("runspec_linux_core.sudoers._runspec_bin_dir", lambda: "/opt/rs/bin")
+
+
+# ── content ───────────────────────────────────────────────────────────────────
+
+
+def test_scoped_content_targets_venv_bin() -> None:
+    out = sudoers._sudoers_content("alice", "scoped", "/opt/rs/bin")
+    assert "alice ALL=(root) NOPASSWD: /opt/rs/bin/\n" in out
+    assert out.startswith("# Managed by runspec-linux")
+
+
+def test_all_content_is_nopasswd_all() -> None:
+    out = sudoers._sudoers_content("alice", "all", "/opt/rs/bin")
+    assert "alice ALL=(ALL) NOPASSWD: ALL\n" in out
+
+
+# ── input validation ──────────────────────────────────────────────────────────
+
+
+def test_rejects_bad_scope() -> None:
+    with pytest.raises(ValueError):
+        sudoers.enable_passwordless_sudo("pw", "alice", "everything")
+
+
+@pytest.mark.parametrize("bad", ["root\nbad ALL=(ALL) NOPASSWD: ALL", "al ice", "-x", "a;b"])
+def test_rejects_injection_in_user(bad: str) -> None:
+    with pytest.raises(ValueError):
+        sudoers.enable_passwordless_sudo("pw", bad, "scoped")
+
+
+# ── install flow ──────────────────────────────────────────────────────────────
+
+
+def test_install_happy_path_pipes_password_via_stdin(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls: list[dict] = []
+
+    def fake_run(cmd, **kw):
+        calls.append({"cmd": cmd, "input": kw.get("input")})
+        if cmd[:2] == ["visudo", "-cf"]:  # local pre-validate
+            return _ok()
+        if cmd[:4] == ["sudo", "-S", "-p", ""]:
+            sub = cmd[4:]  # args after the `sudo -S -p ''` prefix
+            if sub[0] == "cat":  # idempotency probe: not yet installed
+                return _ok(returncode=1, stderr="No such file")
+            if sub[0] == "install":
+                return _ok()
+            if sub[0] == "visudo":  # post-validate
+                return _ok()
+        raise AssertionError(f"unexpected command: {cmd}")
+
+    monkeypatch.setattr("runspec_linux_core.sudoers.subprocess.run", fake_run)
+
+    result = sudoers.enable_passwordless_sudo("s3cret", "alice", "all")
+    assert result == {
+        "user": "alice",
+        "scope": "all",
+        "path": "/etc/sudoers.d/runspec",
+        "installed": True,
+        "already_configured": False,
+    }
+    # Password rides stdin on every sudo call — never appears in any argv.
+    sudo_calls = [c for c in calls if c["cmd"][:1] == ["sudo"]]
+    assert sudo_calls and all(c["input"] == "s3cret\n" for c in sudo_calls)
+    assert not any("s3cret" in " ".join(c["cmd"]) for c in calls)
+
+
+def test_idempotent_when_identical_drop_in_exists(monkeypatch: pytest.MonkeyPatch) -> None:
+    content = sudoers._sudoers_content("alice", "all", "/opt/rs/bin")
+
+    def fake_run(cmd, **kw):
+        if cmd[:2] == ["visudo", "-cf"]:
+            return _ok()
+        if cmd[4:5] == ["cat"]:
+            return _ok(stdout=content)  # already present, identical
+        raise AssertionError(f"should not install: {cmd}")
+
+    monkeypatch.setattr("runspec_linux_core.sudoers.subprocess.run", fake_run)
+    result = sudoers.enable_passwordless_sudo("pw", "alice", "all")
+    assert result["already_configured"] is True
+
+
+def test_wrong_password_raises_command_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_run(cmd, **kw):
+        if cmd[:2] == ["visudo", "-cf"]:
+            return _ok()
+        if cmd[4:5] == ["cat"]:
+            return _ok(returncode=1)
+        if cmd[4:5] == ["install"]:
+            return _ok(returncode=1, stderr="sudo: 1 incorrect password attempt")
+        raise AssertionError(f"unexpected: {cmd}")
+
+    monkeypatch.setattr("runspec_linux_core.sudoers.subprocess.run", fake_run)
+    with pytest.raises(CommandError, match="authentication failed"):
+        sudoers.enable_passwordless_sudo("wrong", "alice", "all")
+
+
+def test_post_validate_failure_rolls_back(monkeypatch: pytest.MonkeyPatch) -> None:
+    removed: list[list[str]] = []
+
+    def fake_run(cmd, **kw):
+        if cmd[:2] == ["visudo", "-cf"]:
+            return _ok()
+        sub = cmd[4:] if cmd[:4] == ["sudo", "-S", "-p", ""] else []
+        if sub[:1] == ["cat"]:
+            return _ok(returncode=1)
+        if sub[:1] == ["install"]:
+            return _ok()
+        if sub[:1] == ["visudo"]:  # whole-tree check fails
+            return _ok(returncode=1, stderr=">>> syntax error")
+        if sub[:1] == ["rm"]:
+            removed.append(sub)
+            return _ok()
+        raise AssertionError(f"unexpected: {cmd}")
+
+    monkeypatch.setattr("runspec_linux_core.sudoers.subprocess.run", fake_run)
+    with pytest.raises(CommandError, match="rolled back"):
+        sudoers.enable_passwordless_sudo("pw", "alice", "scoped")
+    assert removed and removed[0] == ["rm", "-f", "/etc/sudoers.d/runspec"]
+
+
+def test_requires_visudo(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.sudoers.shutil.which", lambda name: None if name == "visudo" else "/usr/bin/sudo")
+    with pytest.raises(ToolNotFoundError, match="visudo"):
+        sudoers.enable_passwordless_sudo("pw", "alice", "scoped")

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`