runspec-linux-root 0.1.0__tar.gz

runspec_linux_root-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_linux_root-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `runspec-linux-root` are documented here.
+
+## [0.1.0] — 2026-09-30
+
+First release. The Linux tools that need root, split out of `runspec-linux`
+(0.19.0) so that package never runs anything as root:
+`list-upgrades`, `upgrade-packages`, `install-package`, `remove-package`,
+`autoremove-packages`, `set-sysctl`, `reboot-host` and
+`enable-passwordless-sudo`.
+
+- Every tool declares `run_as = "root"` (except `enable-passwordless-sudo`,
+  which runs as the invoker and escalates with the password it's given).
+  `set-sysctl` loses its `--run-as`/`--sudo`/`--become-method` args: it always
+  runs as root.
+- Meant for a root-owned venv, so only root can change code that root runs.
+- `enable-passwordless-sudo`'s `scoped` option is documented honestly: it covers
+  direct `sudo <tool>` runs only, not runs from runspec-console or the MCP
+  gateway.
+- The helpers stay in `runspec-linux-core` (>= 0.13.0).

runspec_linux_root-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: runspec-linux-root
+Version: 0.1.0
+Summary: Linux admin runnables that need root (packages, reboot, sysctl) for runspec
+Project-URL: Documentation, https://runspec.app/
+Project-URL: Source, https://github.com/jasonfinestone/runspec/tree/main/packages/python/runspec-linux-root
+Project-URL: Changelog, https://github.com/jasonfinestone/runspec/blob/main/packages/python/runspec-linux-root/CHANGELOG.md
+Project-URL: Issues, https://github.com/jasonfinestone/runspec/issues
+Keywords: linux,packages,root,runnable,runspec,sysadmin
+Requires-Python: >=3.10
+Requires-Dist: runspec-linux-core>=0.13.0
+Requires-Dist: runspec>=0.68.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# runspec-linux-root
+
+Linux admin tools that need **root**, as [runspec](https://runspec.app/) runnables:
+
+| Tool | What it does | Autonomy |
+|---|---|---|
+| `list-upgrades` | List packages with an available upgrade (refreshes the index) | autonomous |
+| `upgrade-packages` | Refresh the index and upgrade every package | confirm |
+| `install-package` | Install packages by name | confirm |
+| `remove-package` | Remove packages (`--purge` for config files too) | confirm |
+| `autoremove-packages` | Remove packages nothing depends on (`--dry-run` to preview) | confirm |
+| `set-sysctl` | Set a kernel parameter, optionally persisted under `/etc/sysctl.d` | confirm |
+| `reboot-host` | Reboot, optionally after a delay | confirm |
+| `enable-passwordless-sudo` | One-time bootstrap: a validated `/etc/sudoers.d` drop-in | confirm |
+
+They work across apt, dnf, yum, zypper and pacman. The logic lives in
+[`runspec-linux-core`](https://pypi.org/project/runspec-linux-core/). The
+everyday tools that never need root are in
+[`runspec-linux`](https://pypi.org/project/runspec-linux/).
+
+## Install into a root-owned venv
+
+Every tool here declares `run_as = "root"`: root runs this code. So install it
+into a venv **only root can change**. A venv owned by a service account would
+let that account edit code root later runs.
+
+```bash
+sudo python3 -m venv /opt/venvs/admin
+sudo /opt/venvs/admin/bin/pip install runspec-linux-root
+```
+
+## Who can run them
+
+sudoers decides. An admin runs a tool with sudo:
+
+```bash
+sudo /opt/venvs/admin/bin/upgrade-packages
+```
+
+runspec checks the process really is root (`enforce_run_as`) and refuses
+otherwise, naming the account to `sudo -u` to.
+
+**From runspec-console or the MCP gateway**, the tool is run with `sudo -n`,
+which never prompts for a password, so the admin needs a passwordless sudo rule.
+`enable-passwordless-sudo` installs one:
+
+- `--scope scoped` allows only this venv's tools, run directly
+  (`sudo /opt/venvs/admin/bin/<tool>` from a shell or cron). It does **not**
+  cover the console or the gateway, which pass variables to the tool through a
+  `sh` prelude so that secrets never go on a command line; sudo then sees `sh`,
+  not the tool.
+- `--scope all` grants `NOPASSWD: ALL`, which the console and the gateway need.

runspec_linux_root-0.1.0/README.md

@@ -0,0 +1,52 @@
+# runspec-linux-root
+
+Linux admin tools that need **root**, as [runspec](https://runspec.app/) runnables:
+
+| Tool | What it does | Autonomy |
+|---|---|---|
+| `list-upgrades` | List packages with an available upgrade (refreshes the index) | autonomous |
+| `upgrade-packages` | Refresh the index and upgrade every package | confirm |
+| `install-package` | Install packages by name | confirm |
+| `remove-package` | Remove packages (`--purge` for config files too) | confirm |
+| `autoremove-packages` | Remove packages nothing depends on (`--dry-run` to preview) | confirm |
+| `set-sysctl` | Set a kernel parameter, optionally persisted under `/etc/sysctl.d` | confirm |
+| `reboot-host` | Reboot, optionally after a delay | confirm |
+| `enable-passwordless-sudo` | One-time bootstrap: a validated `/etc/sudoers.d` drop-in | confirm |
+
+They work across apt, dnf, yum, zypper and pacman. The logic lives in
+[`runspec-linux-core`](https://pypi.org/project/runspec-linux-core/). The
+everyday tools that never need root are in
+[`runspec-linux`](https://pypi.org/project/runspec-linux/).
+
+## Install into a root-owned venv
+
+Every tool here declares `run_as = "root"`: root runs this code. So install it
+into a venv **only root can change**. A venv owned by a service account would
+let that account edit code root later runs.
+
+```bash
+sudo python3 -m venv /opt/venvs/admin
+sudo /opt/venvs/admin/bin/pip install runspec-linux-root
+```
+
+## Who can run them
+
+sudoers decides. An admin runs a tool with sudo:
+
+```bash
+sudo /opt/venvs/admin/bin/upgrade-packages
+```
+
+runspec checks the process really is root (`enforce_run_as`) and refuses
+otherwise, naming the account to `sudo -u` to.
+
+**From runspec-console or the MCP gateway**, the tool is run with `sudo -n`,
+which never prompts for a password, so the admin needs a passwordless sudo rule.
+`enable-passwordless-sudo` installs one:
+
+- `--scope scoped` allows only this venv's tools, run directly
+  (`sudo /opt/venvs/admin/bin/<tool>` from a shell or cron). It does **not**
+  cover the console or the gateway, which pass variables to the tool through a
+  `sh` prelude so that secrets never go on a command line; sudo then sees `sh`,
+  not the tool.
+- `--scope all` grants `NOPASSWD: ALL`, which the console and the gateway need.

runspec_linux_root-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-linux-root"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Linux admin runnables that need root (packages, reboot, sysctl) for runspec"
+readme = "README.md"
+keywords = ["runspec", "runnable", "linux", "sysadmin", "root", "packages"]
+dependencies = [
+    "runspec>=0.68.0",
+    "runspec-linux-core>=0.13.0",
+]
+
+[project.urls]
+Documentation = "https://runspec.app/"
+Source        = "https://github.com/jasonfinestone/runspec/tree/main/packages/python/runspec-linux-root"
+Changelog     = "https://github.com/jasonfinestone/runspec/blob/main/packages/python/runspec-linux-root/CHANGELOG.md"
+Issues        = "https://github.com/jasonfinestone/runspec/issues"
+
+[project.scripts]
+list-upgrades       = "runspec_linux_root.packages:main_list_upgrades"
+upgrade-packages    = "runspec_linux_root.packages:main_upgrade_packages"
+install-package     = "runspec_linux_root.packages:main_install_package"
+remove-package      = "runspec_linux_root.packages:main_remove_package"
+autoremove-packages = "runspec_linux_root.packages:main_autoremove_packages"
+set-sysctl          = "runspec_linux_root.perf:main_set_sysctl"
+reboot-host         = "runspec_linux_root.power:main_reboot_host"
+enable-passwordless-sudo = "runspec_linux_root.sudoers:main_enable_passwordless_sudo"
+
+[project.optional-dependencies]
+dev = [
+    "ruff==0.15.20",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_linux_root-0.1.0/runspec_linux_root/__init__.py

@@ -0,0 +1,7 @@
+"""runspec-linux-root — Linux admin runnables that need root.
+
+Package management, reboot and kernel tuning, split out of ``runspec-linux`` so
+that package never runs anything as root. Every tool here declares
+``run_as = "root"``. Install it into a **root-owned** venv: root runs this code,
+so only root may be able to change it. The logic lives in ``runspec-linux-core``.
+"""

runspec_linux_root-0.1.0/runspec_linux_root/packages.py

@@ -0,0 +1,71 @@
+"""Package-manager runnables that need root (apt/dnf/yum/zypper/pacman)."""
+
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import autoremove_packages, install_package, list_upgrades, remove_package, upgrade_packages
+from runspec_linux_core.errors import CommandError
+
+
+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, purge=spec.purge.value)))
+    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)
+
+
+def main_autoremove_packages() -> None:
+    spec = rs.parse("autoremove-packages")
+    try:
+        print(json.dumps(autoremove_packages(purge=spec.purge.value, dry_run=spec.dry_run.value)))
+    except CommandError as e:
+        print(json.dumps({"removed": 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)

runspec_linux_root-0.1.0/runspec_linux_root/perf.py

@@ -0,0 +1,23 @@
+"""Kernel tuning that needs root."""
+
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import set_sysctl
+from runspec_linux_core.errors import CommandError
+
+
+def main_set_sysctl() -> None:
+    spec = rs.parse("set-sysctl")
+    key = spec.key.value
+    value = spec.value.value
+    persist = spec.persist.value
+    try:
+        print(json.dumps(set_sysctl(key, value, persist=persist)))
+    except CommandError as e:
+        print(json.dumps({"key": key, "applied": False, "error": str(e)}))
+        sys.exit(1)
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux_root-0.1.0/runspec_linux_root/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_root-0.1.0/runspec_linux_root/runspec.toml

@@ -0,0 +1,145 @@
+# runspec-linux-root — Linux admin tools that need root.
+#
+# Install into a ROOT-OWNED venv (e.g. sudo python3 -m venv /opt/venvs/admin):
+# root runs this code, so only root may be able to change it. Every tool declares
+# run_as = "root"; sudoers decides who may run them.
+
+[config]
+autonomy-default = "confirm"
+
+[config.logging]
+store = "per-run"
+
+# ── Packages ──────────────────────────────────────────────────────────────────
+
+[list-upgrades]
+serve       = ["local"]
+description = "List packages with an available upgrade (refreshes the package index first)"
+autonomy    = "autonomous"
+output      = "json"
+run_as      = "root"
+
+[list-upgrades.args.no-refresh]
+type        = "flag"
+description = "Skip refreshing the package index — list from the cached index (faster)"
+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)"
+
+[remove-package.args.purge]
+type        = "flag"
+description = "Also delete the packages' configuration files (apt purge / pacman -Rn; a plain remove on dnf/yum/zypper)"
+default     = false
+
+[autoremove-packages]
+serve       = ["local"]
+description = "Remove packages nothing depends on any more, e.g. old kernels (apt autoremove and equivalents; needs root)"
+autonomy    = "confirm"
+output      = "json"
+run_as      = "root"
+
+[autoremove-packages.args.purge]
+type        = "flag"
+description = "Also delete the removed packages' configuration files (apt --purge / pacman -n)"
+default     = false
+
+[autoremove-packages.args.dry-run]
+type        = "flag"
+description = "Only list what would be removed; remove nothing (not supported on yum). list-autoremovable does the same without needing approval"
+default     = false
+
+# ── Kernel ────────────────────────────────────────────────────────────────────
+
+[set-sysctl]
+serve       = ["local"]
+description = "Set a kernel parameter (sysctl -w), optionally persisting it under /etc/sysctl.d (needs root)"
+autonomy    = "confirm"
+output      = "json"
+run_as      = "root"
+
+[set-sysctl.args.key]
+type        = "str"
+short       = "-k"
+description = "Dotted sysctl key (e.g. net.core.somaxconn)"
+
+[set-sysctl.args.value]
+type        = "str"
+description = "New value to set"
+
+[set-sysctl.args.persist]
+type        = "flag"
+description = "Also append the setting to /etc/sysctl.d/99-runspec.conf so it survives a reboot"
+default     = false
+
+# ── 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 runs as the invoker (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"
+run_as      = ""
+
+[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 this venv's tools, run directly (sudo <venv>/bin/<tool> from a shell or cron); all = NOPASSWD: ALL (also needed for runs from runspec-console or the MCP gateway)"

runspec_linux_root-0.1.0/runspec_linux_root/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_root-0.1.0/tests/test_spec.py

@@ -0,0 +1,65 @@
+"""Shape of the root package's runspec.toml and entry points."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+import pytest
+
+tomllib = pytest.importorskip("tomllib")
+
+SPEC = tomllib.loads((files("runspec_linux_root") / "runspec.toml").read_text())
+RUNNABLES = {k: v for k, v in SPEC.items() if k != "config"}
+
+
+def test_every_tool_runs_as_root_except_the_bootstrap() -> None:
+    for name, body in RUNNABLES.items():
+        expected = "" if name == "enable-passwordless-sudo" else "root"
+        assert body.get("run_as") == expected, name
+
+
+def test_no_per_invocation_escalation_args() -> None:
+    for name, body in RUNNABLES.items():
+        args = body.get("args") or {}
+        assert not {"run-as", "sudo", "become-method"} & set(args), name
+
+
+def test_mutating_tools_need_confirmation() -> None:
+    for name, body in RUNNABLES.items():
+        if name != "list-upgrades":
+            assert body.get("autonomy", SPEC["config"]["autonomy-default"]) == "confirm", name
+
+
+def test_entry_points_match_runnables() -> None:
+    import runspec_linux_root.packages as packages
+    import runspec_linux_root.perf as perf
+    import runspec_linux_root.power as power
+    import runspec_linux_root.sudoers as sudoers
+
+    mains = {
+        "list-upgrades": packages.main_list_upgrades,
+        "upgrade-packages": packages.main_upgrade_packages,
+        "install-package": packages.main_install_package,
+        "remove-package": packages.main_remove_package,
+        "autoremove-packages": packages.main_autoremove_packages,
+        "set-sysctl": perf.main_set_sysctl,
+        "reboot-host": power.main_reboot_host,
+        "enable-passwordless-sudo": sudoers.main_enable_passwordless_sudo,
+    }
+    assert set(mains) == set(RUNNABLES)
+
+
+def test_set_sysctl_runs_the_core_helper_without_escalating(monkeypatch, capsys) -> None:
+    # Already root (run_as = "root"), so the wrapper passes no run_as of its own.
+    import json
+
+    import runspec_linux_root.perf as perf
+
+    calls = []
+    monkeypatch.setattr(perf, "set_sysctl", lambda key, value, **kw: calls.append((key, value, kw)) or {"key": key, "applied": True})
+    monkeypatch.setattr("sys.argv", ["set-sysctl", "--key", "vm.swappiness", "--value", "10"])
+    # The suite doesn't run as root; stub the identity check the parser uses.
+    monkeypatch.setattr("runspec.parser.verify_run_as_identity", lambda user: None)
+    perf.main_set_sysctl()
+    assert calls == [("vm.swappiness", "10", {"persist": False})]
+    assert json.loads(capsys.readouterr().out)["applied"] is True