runspec-linux 0.2.0__tar.gz → 0.4.0__tar.gz

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/CHANGELOG.md

@@ -1,5 +1,59 @@
 # runspec-linux Changelog
 
+## [0.4.0] — 2026-06-20
+
+Make the privileged package/power runnables escalate via runspec's `run_as`, and
+add a one-time bootstrap runnable to enable it without a password. Bumps the
+`runspec-linux-core` floor to `>=0.3.0`.
+
+- **`run_as = "root"`** on `upgrade-packages`, `install-package`,
+  `remove-package`, and `reboot-host`. The console's SSH executor now wraps these
+  in `sudo -u root …` before they run, instead of failing with permission denied
+  when the SSH login user isn't root. (`list-packages` / `list-upgrades` stay
+  un-escalated — least privilege; `list-upgrades --no-refresh` works as any user.)
+  A site with a service account can override `run_as` in its own spec.
+- **New `enable-passwordless-sudo`** (confirm) — the one-time setup that makes the
+  above work password-free. Takes a **`password`-typed** arg (delivered over the
+  console's secret channel and piped to `sudo -S` — never on argv/ps/logs),
+  optional `--user` (defaults to the login user), and `--scope`
+  (`scoped` = the runspec venv runnables only; `all` = `NOPASSWD: ALL`). Installs
+  a `visudo`-validated `/etc/sudoers.d/runspec`, rolling back on a bad result. It
+  declares no `run_as` (it bootstraps root itself).
+
+Setup flow: run `enable-passwordless-sudo` once per host (pick `all` for
+agent-driven fleet management; `scoped` is enough for manual/CLI runs), then
+`upgrade-packages` and friends run without a password.
+
+## [0.3.0] — 2026-06-20
+
+Add 6 runnables for managing a fleet's packages and power state from
+runspec-console — thin wrappers over the new `runspec-linux-core` 0.2.0 helpers
+(dependency floor bumped to `>=0.2.0`). They work across the common distro
+families (apt/dnf/yum/zypper/pacman).
+
+**Packages**
+
+- `list-packages` (autonomous) — list installed packages, optional `--filter`
+  substring and `--limit`.
+- `list-upgrades` (autonomous) — list packages with an available upgrade;
+  refreshes the index first, or pass `--no-refresh` to read the cache without
+  root.
+- `upgrade-packages` (confirm) — refresh the index and upgrade everything.
+- `install-package` (confirm) — install one or more packages (`--package`,
+  space-separated for several).
+- `remove-package` (confirm) — remove one or more packages.
+
+**Power**
+
+- `reboot-host` (confirm) — reboot the host now, or schedule with
+  `--delay-minutes`.
+
+The read-only runnables are `autonomous`; the state-changing ones are `confirm`,
+matching `restart-service` / `restart-container`. Missing package manager / a
+non-root failure returns structured JSON (`{... false, "error": ...}`) and a
+non-zero exit rather than a stack trace; package names are validated before they
+reach the package manager.
+
 ## [0.2.0] — 2026-06-09
 
 Split the pure logic out into a new dependency-free package,

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: runspec-linux
-Version: 0.2.0
+Version: 0.4.0
 Summary: Linux system admin runnables for runspec
 Requires-Python: >=3.10
-Requires-Dist: runspec-linux-core>=0.1.0
+Requires-Dist: runspec-linux-core>=0.3.0
 Requires-Dist: runspec>=0.27.0
 Provides-Extra: dev
 Requires-Dist: mypy; extra == 'dev'

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux"
-version = "0.2.0"
+version = "0.4.0"
 requires-python = ">=3.10"
 description = "Linux system admin runnables for runspec"
 dependencies = [
     "runspec>=0.27.0",
-    "runspec-linux-core>=0.1.0",
+    "runspec-linux-core>=0.3.0",
 ]
 
 [project.scripts]
@@ -33,6 +33,13 @@ who               = "runspec_linux.security:main_who"
 list-containers   = "runspec_linux.containers:main_list_containers"
 container-logs    = "runspec_linux.containers:main_container_logs"
 restart-container = "runspec_linux.containers:main_restart_container"
+list-packages     = "runspec_linux.packages:main_list_packages"
+list-upgrades     = "runspec_linux.packages:main_list_upgrades"
+upgrade-packages  = "runspec_linux.packages:main_upgrade_packages"
+install-package   = "runspec_linux.packages:main_install_package"
+remove-package    = "runspec_linux.packages:main_remove_package"
+reboot-host       = "runspec_linux.power:main_reboot_host"
+enable-passwordless-sudo = "runspec_linux.sudoers:main_enable_passwordless_sudo"
 nc-command        = "runspec_linux.nc_command:main"
 
 [project.optional-dependencies]

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/runspec_linux/__init__.py

@@ -13,21 +13,29 @@ from runspec_linux_core import (
     check_port,
     check_service,
     container_logs,
+    detect_manager,
     disk_usage,
+    enable_passwordless_sudo,
     find_large_files,
+    install_package,
     journalctl,
     last_logins,
     list_containers,
+    list_packages,
     list_processes,
     list_services,
+    list_upgrades,
     nc_send,
     ping_host,
+    reboot_host,
+    remove_package,
     restart_container,
     restart_service,
     search_log,
     show_connections,
     system_info,
     tail_log,
+    upgrade_packages,
     who,
 )
 
@@ -37,20 +45,28 @@ __all__ = [
     "check_port",
     "check_service",
     "container_logs",
+    "detect_manager",
     "disk_usage",
+    "enable_passwordless_sudo",
     "find_large_files",
+    "install_package",
     "journalctl",
     "last_logins",
     "list_containers",
+    "list_packages",
     "list_processes",
     "list_services",
+    "list_upgrades",
     "nc_send",
     "ping_host",
+    "reboot_host",
+    "remove_package",
     "restart_container",
     "restart_service",
     "search_log",
     "show_connections",
     "system_info",
     "tail_log",
+    "upgrade_packages",
     "who",
 ]

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/runspec_linux/containers.py

@@ -8,7 +8,7 @@ from runspec_linux_core.errors import CommandError
 
 def main_list_containers() -> None:
     spec = rs.parse("list-containers")
-    include_all = bool(spec.all)
+    include_all = spec.all.value
     try:
         print(json.dumps(list_containers(include_all)))
     except Exception as e:
@@ -19,8 +19,8 @@ def main_list_containers() -> None:
 
 def main_container_logs() -> None:
     spec = rs.parse("container-logs")
-    container = str(spec.container)
-    lines = int(spec.lines)
+    container = spec.container.value
+    lines = spec.lines.value
     try:
         print(json.dumps(container_logs(container, lines)))
     except Exception as e:
@@ -30,7 +30,7 @@ def main_container_logs() -> None:
 
 def main_restart_container() -> None:
     spec = rs.parse("restart-container")
-    container = str(spec.container)
+    container = spec.container.value
     try:
         print(json.dumps(restart_container(container)))
     except CommandError as e:

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/runspec_linux/files.py

@@ -7,9 +7,9 @@ from runspec_linux_core import backup_files, find_large_files
 
 def main_find_large_files() -> None:
     spec = rs.parse("find-large-files")
-    search_path = str(spec.path)
-    min_mb = float(spec.min_mb)
-    limit = int(spec.limit)
+    search_path = str(spec.path.value)
+    min_mb = spec.min_mb.value
+    limit = spec.limit.value
     try:
         print(json.dumps(find_large_files(search_path, min_mb, limit)))
     except Exception as e:
@@ -19,8 +19,8 @@ def main_find_large_files() -> None:
 
 def main_backup_files() -> None:
     spec = rs.parse("backup-files")
-    source = str(spec.source)
-    destination = str(spec.destination)
+    source = str(spec.source.value)
+    destination = str(spec.destination.value)
     try:
         print(json.dumps(backup_files(source, destination)))
     except Exception as e:

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/runspec_linux/logs.py

@@ -10,8 +10,8 @@ from runspec_linux_core.errors import ToolNotFoundError
 
 def main_tail_log() -> None:
     spec = rs.parse("tail-log")
-    file_path = str(spec.file)
-    lines = int(spec.lines)
+    file_path = str(spec.file.value)
+    lines = spec.lines.value
     try:
         print(json.dumps(tail_log(file_path, lines)))
     except OSError as e:
@@ -21,9 +21,9 @@ def main_tail_log() -> None:
 
 def main_search_log() -> None:
     spec = rs.parse("search-log")
-    file_path = str(spec.file)
-    pattern = str(spec.pattern)
-    limit = int(spec.limit)
+    file_path = str(spec.file.value)
+    pattern = spec.pattern.value
+    limit = spec.limit.value
     try:
         print(json.dumps(search_log(file_path, pattern, limit)))
     except OSError as e:
@@ -36,9 +36,9 @@ def main_search_log() -> None:
 
 def main_journalctl() -> None:
     spec = rs.parse("journalctl")
-    unit = str(spec.unit)
-    lines = int(spec.lines)
-    since = str(spec.since) if spec.since is not None else None
+    unit = spec.unit.value
+    lines = spec.lines.value
+    since = spec.since.value
     try:
         print(json.dumps(journalctl(unit, lines, since)))
     except ToolNotFoundError as e:

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/runspec_linux/nc_command.py

@@ -13,11 +13,11 @@ __all__ = ["main", "nc_send"]
 
 def main() -> None:
     spec = rs.parse("nc-command")
-    host = str(spec.host)
-    port = int(spec.port)
-    command = str(spec.command)
-    wait = float(spec.wait)
-    read_timeout = float(spec.read_timeout)
+    host = spec.host.value
+    port = spec.port.value
+    command = spec.command.value
+    wait = spec.wait.value
+    read_timeout = spec.read_timeout.value
 
     try:
         response = nc_send(host, port, command, wait=wait, read_timeout=read_timeout)

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/runspec_linux/network.py

@@ -7,8 +7,8 @@ from runspec_linux_core import check_port, ping_host, show_connections
 
 def main_ping_host() -> None:
     spec = rs.parse("ping-host")
-    host = str(spec.host)
-    count = int(spec.count)
+    host = spec.host.value
+    count = spec.count.value
     try:
         print(json.dumps(ping_host(host, count)))
     except Exception as e:
@@ -18,15 +18,15 @@ def main_ping_host() -> None:
 
 def main_check_port() -> None:
     spec = rs.parse("check-port")
-    host = str(spec.host)
-    port = int(spec.port)
-    timeout = float(spec.timeout)
+    host = spec.host.value
+    port = spec.port.value
+    timeout = spec.timeout.value
     print(json.dumps(check_port(host, port, timeout)))
 
 
 def main_show_connections() -> None:
     spec = rs.parse("show-connections")
-    state_filter = str(spec.state)
+    state_filter = spec.state.value
     try:
         print(json.dumps(show_connections(state_filter)))
     except Exception as e:

runspec_linux-0.4.0/runspec_linux/packages.py

@@ -0,0 +1,74 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import (
+    install_package,
+    list_packages,
+    list_upgrades,
+    remove_package,
+    upgrade_packages,
+)
+from runspec_linux_core.errors import CommandError
+
+
+def main_list_packages() -> None:
+    spec = rs.parse("list-packages")
+    name_filter = spec.filter.value
+    limit = spec.limit.value
+    try:
+        print(json.dumps(list_packages(name_filter, limit)))
+    except Exception as e:
+        # Includes ToolNotFoundError (no package manager) and CommandError.
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_list_upgrades() -> None:
+    spec = rs.parse("list-upgrades")
+    try:
+        print(json.dumps(list_upgrades(refresh=not spec.no_refresh.value)))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_upgrade_packages() -> None:
+    rs.parse("upgrade-packages")
+    try:
+        print(json.dumps(upgrade_packages()))
+    except CommandError as e:
+        print(json.dumps({"upgraded": False, "error": str(e)}))
+        sys.exit(1)
+    except Exception as e:
+        # Includes ToolNotFoundError (no package manager).
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_install_package() -> None:
+    spec = rs.parse("install-package")
+    package = spec.package.value
+    try:
+        print(json.dumps(install_package(package)))
+    except CommandError as e:
+        print(json.dumps({"package": package, "installed": False, "error": str(e)}))
+        sys.exit(1)
+    except Exception as e:
+        # Includes ValueError (bad name) and ToolNotFoundError (no package manager).
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_remove_package() -> None:
+    spec = rs.parse("remove-package")
+    package = spec.package.value
+    try:
+        print(json.dumps(remove_package(package)))
+    except CommandError as e:
+        print(json.dumps({"package": package, "removed": False, "error": str(e)}))
+        sys.exit(1)
+    except Exception as e:
+        # Includes ValueError (bad name) and ToolNotFoundError (no package manager).
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux-0.4.0/runspec_linux/power.py

@@ -0,0 +1,20 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import reboot_host
+from runspec_linux_core.errors import CommandError
+
+
+def main_reboot_host() -> None:
+    spec = rs.parse("reboot-host")
+    delay_minutes = spec.delay_minutes.value
+    try:
+        print(json.dumps(reboot_host(delay_minutes)))
+    except CommandError as e:
+        print(json.dumps({"scheduled": False, "error": str(e)}))
+        sys.exit(1)
+    except Exception as e:
+        # Includes ToolNotFoundError (no shutdown/systemctl).
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/runspec_linux/runspec.toml

@@ -299,6 +299,111 @@ type        = "str"
 short       = "-c"
 description = "Container name or ID"
 
+# ── Packages ──────────────────────────────────────────────────────────────────
+
+[list-packages]
+serve       = ["local"]
+description = "List installed packages (apt/dnf/yum/zypper/pacman), optionally filtered by name"
+autonomy    = "autonomous"
+output      = "json"
+
+[list-packages.args.filter]
+type        = "str"
+short       = "-f"
+description = "Only list packages whose name contains this string"
+required    = false
+
+[list-packages.args.limit]
+type        = "int"
+short       = "-n"
+description = "Maximum number of packages to return (sorted by name)"
+default     = 100
+
+[list-upgrades]
+serve       = ["local"]
+description = "List packages with an available upgrade (refreshes the package index first)"
+autonomy    = "autonomous"
+output      = "json"
+
+[list-upgrades.args.no-refresh]
+type        = "flag"
+description = "Read the cached package index instead of refreshing it first (no root needed)"
+default     = false
+
+[upgrade-packages]
+serve       = ["local"]
+description = "Refresh the package index and upgrade all installed packages (needs root)"
+autonomy    = "confirm"
+output      = "json"
+run_as      = "root"
+
+[install-package]
+serve       = ["local"]
+description = "Install one or more packages by name (needs root)"
+autonomy    = "confirm"
+output      = "json"
+run_as      = "root"
+
+[install-package.args.package]
+type        = "str"
+short       = "-p"
+description = "Package name to install (space-separated for several)"
+
+[remove-package]
+serve       = ["local"]
+description = "Remove one or more packages by name (needs root)"
+autonomy    = "confirm"
+output      = "json"
+run_as      = "root"
+
+[remove-package.args.package]
+type        = "str"
+short       = "-p"
+description = "Package name to remove (space-separated for several)"
+
+# ── Power ─────────────────────────────────────────────────────────────────────
+
+[reboot-host]
+serve       = ["local"]
+description = "Reboot the host, optionally after a delay in minutes (needs root)"
+autonomy    = "confirm"
+output      = "json"
+run_as      = "root"
+
+[reboot-host.args.delay-minutes]
+type        = "int"
+short       = "-d"
+description = "Minutes to wait before rebooting (0 = immediately)"
+default     = 0
+
+# ── Privilege bootstrap ───────────────────────────────────────────────────────
+
+# One-time setup so the run_as="root" runnables above need no password. Itself
+# escalates with the supplied password via `sudo -S` (read from stdin, never
+# argv), so it must NOT declare run_as. Validated with visudo before + after
+# install and rolled back on failure.
+[enable-passwordless-sudo]
+serve       = ["local"]
+description = "Install a validated /etc/sudoers.d drop-in so run_as='root' runnables need no password (one-time bootstrap)"
+autonomy    = "confirm"
+output      = "json"
+
+[enable-passwordless-sudo.args.password]
+type        = "password"
+description = "Your sudo password — sent over the secret channel and piped to 'sudo -S'; never appears in argv, ps, or logs"
+
+[enable-passwordless-sudo.args.user]
+type        = "str"
+short       = "-u"
+description = "User to grant passwordless sudo (defaults to the current login user)"
+required    = false
+
+[enable-passwordless-sudo.args.scope]
+type        = "choice"
+options     = ["scoped", "all"]
+default     = "scoped"
+description = "scoped = NOPASSWD only for the runspec venv runnables (manual/CLI runs); all = NOPASSWD: ALL (also covers agent-driven runs)"
+
 # ── TCP interfaces (nc-command) ────────────────────────────────────────────────
 
 [nc-command]

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/runspec_linux/security.py

@@ -7,7 +7,7 @@ from runspec_linux_core import last_logins, who
 
 def main_last_logins() -> None:
     spec = rs.parse("last-logins")
-    limit = int(spec.limit)
+    limit = spec.limit.value
     try:
         print(json.dumps(last_logins(limit)))
     except Exception as e:

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/runspec_linux/services.py

@@ -8,7 +8,7 @@ from runspec_linux_core.errors import CommandError
 
 def main_check_service() -> None:
     spec = rs.parse("check-service")
-    service = str(spec.service)
+    service = spec.service.value
     try:
         print(json.dumps(check_service(service)))
     except Exception as e:
@@ -18,7 +18,7 @@ def main_check_service() -> None:
 
 def main_list_services() -> None:
     spec = rs.parse("list-services")
-    state_filter = str(spec.state)
+    state_filter = spec.state.value
     try:
         print(json.dumps(list_services(state_filter)))
     except Exception as e:
@@ -28,7 +28,7 @@ def main_list_services() -> None:
 
 def main_restart_service() -> None:
     spec = rs.parse("restart-service")
-    service = str(spec.service)
+    service = spec.service.value
     try:
         print(json.dumps(restart_service(service)))
     except CommandError as e:

runspec_linux-0.4.0/runspec_linux/sudoers.py

@@ -0,0 +1,23 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import enable_passwordless_sudo
+from runspec_linux_core.errors import CommandError
+
+
+def main_enable_passwordless_sudo() -> None:
+    spec = rs.parse("enable-passwordless-sudo")
+    password = spec.password.value
+    user = spec.user.value
+    scope = spec.scope.value
+    try:
+        print(json.dumps(enable_passwordless_sudo(password, user, scope)))
+    except CommandError as e:
+        # Auth failure / sudoers validation failure (rolled back).
+        print(json.dumps({"installed": False, "error": str(e)}))
+        sys.exit(1)
+    except Exception as e:
+        # Includes ValueError (bad scope/user) and ToolNotFoundError (no sudo/visudo).
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

{runspec_linux-0.2.0 → runspec_linux-0.4.0}/runspec_linux/system_info.py

@@ -34,8 +34,8 @@ def main_check_memory() -> None:
 
 def main_list_processes() -> None:
     spec = rs.parse("list-processes")
-    name_filter = str(spec.filter) if spec.filter is not None else None
-    limit = int(spec.limit)
+    name_filter = spec.filter.value
+    limit = spec.limit.value
     try:
         print(json.dumps(list_processes(name_filter, limit)))
     except Exception as e: