runspec-linux 0.1.3__tar.gz → 0.3.0__tar.gz

{runspec_linux-0.1.3 → runspec_linux-0.3.0}/.gitignore

@@ -56,3 +56,6 @@ chainlit-docs/
 
 # Claude Code local config (machine-specific)
 .claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_linux-0.3.0/CHANGELOG.md

@@ -0,0 +1,99 @@
+# runspec-linux Changelog
+
+## [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-core`**, and make `runspec-linux` depend on it. Every runnable
+module is now a thin wrapper: it parses args via `runspec`, calls the matching
+`runspec_linux_core` function, and renders the JSON/exit behaviour. The helper
+functions are re-exported from `runspec_linux` for back-compat
+(`from runspec_linux import nc_send` and friends still work), and
+`runspec_linux.nc_command.nc_send` is preserved.
+
+Why: importing a helper (e.g. `nc_send`) previously required installing
+`runspec-linux`, which put all 21 console scripts on PATH and surfaced all 21
+runnables in `runspec local` / `runspec serve`. Code that only wants the
+importable helpers can now depend on `runspec-linux-core` instead — it has no
+`runspec` dependency, no `runspec.toml`, and no entry points, so it surfaces
+nothing. No behaviour change for the runnables themselves; JSON output and exit
+codes are unchanged.
+
+## [0.1.3] — 2026-06-04
+
+Switch `[config.logging]` to `store = "per-run"` so every runnable writes one
+log file per invocation (`{runnable}.{utc-ts}.{run_id}.log`) instead of a single
+shared rotating `{runnable}.log`. These runnables are meant to be installed into
+shared venvs and run by multiple users (and in parallel); per-invocation files
+are multi-writer safe — no in-process rotation and no contention over one file.
+Use `runspec logs` to view, compact, and prune. The `rotate`/`keep` keys (inert
+under per-run) are dropped. Bumps the `runspec` dependency floor to `>=0.27.0`,
+where `store = "per-run"` was introduced.
+
+## [0.1.2] — 2026-06-02
+
+Lower the Python floor to 3.10 to match the core `runspec` library (no
+3.11-only features are used). Bump the `runspec` dependency floor to
+`>=0.23.0`.
+
+## [0.1.1] — 2026-05-28
+
+Enable `[config.logging]` for all 21 runnables. Each invocation now writes a
+JSON audit record to `{venv}/logs/{runnable}.log` (rotates at 10 MB, keeps 14
+backups) and emits a one-line run summary to stderr. The auto-added `--debug`
+and `--no-summary` flags are available on every runnable. No code changes —
+existing `print(json.dumps(...))` payloads are captured into the audit log via
+the print-capture mechanism; stdout stays clean for pipe consumers.
+
+## [0.1.0] — 2026-05-27
+
+Initial release.
+
+21 runnables covering Linux system administration:
+
+**System monitoring** — `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 interfaces** — `nc-command` (also exports `nc_send()` as a public Python API for wrapper runnables)
+
+All read-only runnables are `autonomy = "autonomous"`. State-changing runnables (`restart-service`, `backup-files`, `restart-container`) are `autonomy = "confirm"`. Missing tools (`docker`, `systemctl`, `journalctl`) return a structured JSON error rather than a stack trace.

{runspec_linux-0.1.3 → runspec_linux-0.3.0}/PKG-INFO

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

{runspec_linux-0.1.3 → runspec_linux-0.3.0}/pyproject.toml

@@ -4,11 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux"
-version = "0.1.3"
+version = "0.3.0"
 requires-python = ">=3.10"
 description = "Linux system admin runnables for runspec"
 dependencies = [
     "runspec>=0.27.0",
+    "runspec-linux-core>=0.2.0",
 ]
 
 [project.scripts]
@@ -32,6 +33,12 @@ 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"
 nc-command        = "runspec_linux.nc_command:main"
 
 [project.optional-dependencies]

runspec_linux-0.3.0/runspec_linux/__init__.py

@@ -0,0 +1,70 @@
+"""runspec-linux — Linux system-admin runnables.
+
+The pure logic lives in the dependency-free ``runspec-linux-core`` package; the
+modules here wrap each helper in a runspec runnable. The helper functions are
+re-exported for convenience and back-compat (e.g. ``from runspec_linux import
+nc_send``). To import the helpers *without* surfacing any runnables in a venv,
+depend on ``runspec-linux-core`` directly instead.
+"""
+
+from runspec_linux_core import (
+    backup_files,
+    check_memory,
+    check_port,
+    check_service,
+    container_logs,
+    detect_manager,
+    disk_usage,
+    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,
+)
+
+__all__ = [
+    "backup_files",
+    "check_memory",
+    "check_port",
+    "check_service",
+    "container_logs",
+    "detect_manager",
+    "disk_usage",
+    "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.3.0/runspec_linux/containers.py

@@ -0,0 +1,42 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import container_logs, list_containers, restart_container
+from runspec_linux_core.errors import CommandError
+
+
+def main_list_containers() -> None:
+    spec = rs.parse("list-containers")
+    include_all = spec.all.value
+    try:
+        print(json.dumps(list_containers(include_all)))
+    except Exception as e:
+        # Includes ToolNotFoundError (docker absent) and CommandError (docker ps failed).
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_container_logs() -> None:
+    spec = rs.parse("container-logs")
+    container = spec.container.value
+    lines = spec.lines.value
+    try:
+        print(json.dumps(container_logs(container, lines)))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_restart_container() -> None:
+    spec = rs.parse("restart-container")
+    container = spec.container.value
+    try:
+        print(json.dumps(restart_container(container)))
+    except CommandError as e:
+        print(json.dumps({"container": container, "restarted": False, "error": str(e)}))
+        sys.exit(1)
+    except Exception as e:
+        # Includes ToolNotFoundError (docker absent).
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux-0.3.0/runspec_linux/files.py

@@ -0,0 +1,28 @@
+import json
+import sys
+
+import runspec as rs
+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.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:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_backup_files() -> None:
+    spec = rs.parse("backup-files")
+    source = str(spec.source.value)
+    destination = str(spec.destination.value)
+    try:
+        print(json.dumps(backup_files(source, destination)))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux-0.3.0/runspec_linux/logs.py

@@ -0,0 +1,52 @@
+import json
+import re
+import subprocess
+import sys
+
+import runspec as rs
+from runspec_linux_core import journalctl, search_log, tail_log
+from runspec_linux_core.errors import ToolNotFoundError
+
+
+def main_tail_log() -> None:
+    spec = rs.parse("tail-log")
+    file_path = str(spec.file.value)
+    lines = spec.lines.value
+    try:
+        print(json.dumps(tail_log(file_path, lines)))
+    except OSError as e:
+        print(json.dumps({"error": str(e), "file": file_path}))
+        sys.exit(1)
+
+
+def main_search_log() -> None:
+    spec = rs.parse("search-log")
+    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:
+        print(json.dumps({"error": str(e), "file": file_path}))
+        sys.exit(1)
+    except re.error as e:
+        print(json.dumps({"error": f"Invalid regex: {e}", "pattern": pattern}))
+        sys.exit(1)
+
+
+def main_journalctl() -> None:
+    spec = rs.parse("journalctl")
+    unit = spec.unit.value
+    lines = spec.lines.value
+    since = spec.since.value
+    try:
+        print(json.dumps(journalctl(unit, lines, since)))
+    except ToolNotFoundError as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+    except subprocess.CalledProcessError as e:
+        print(json.dumps({"error": e.stderr.strip(), "unit": unit}))
+        sys.exit(1)
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux-0.3.0/runspec_linux/nc_command.py

@@ -0,0 +1,38 @@
+import json
+import sys
+
+import runspec as rs
+
+# Re-exported for back-compat: callers historically did
+# `from runspec_linux.nc_command import nc_send`. The implementation now lives
+# in the dependency-free runspec-linux-core package.
+from runspec_linux_core import nc_send
+
+__all__ = ["main", "nc_send"]
+
+
+def main() -> None:
+    spec = rs.parse("nc-command")
+    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)
+        lines = response.splitlines()
+        print(
+            json.dumps(
+                {
+                    "host": host,
+                    "port": port,
+                    "command": command,
+                    "stdout": response,
+                    "lines": lines,
+                }
+            )
+        )
+    except OSError as e:
+        print(json.dumps({"error": str(e), "host": host, "port": port}))
+        sys.exit(1)

runspec_linux-0.3.0/runspec_linux/network.py

@@ -0,0 +1,34 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import check_port, ping_host, show_connections
+
+
+def main_ping_host() -> None:
+    spec = rs.parse("ping-host")
+    host = spec.host.value
+    count = spec.count.value
+    try:
+        print(json.dumps(ping_host(host, count)))
+    except Exception as e:
+        print(json.dumps({"error": str(e), "host": host}))
+        sys.exit(1)
+
+
+def main_check_port() -> None:
+    spec = rs.parse("check-port")
+    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 = spec.state.value
+    try:
+        print(json.dumps(show_connections(state_filter)))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux-0.3.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.3.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.1.3 → runspec_linux-0.3.0}/runspec_linux/runspec.toml

@@ -299,6 +299,79 @@ 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"
+
+[install-package]
+serve       = ["local"]
+description = "Install one or more packages by name (needs root)"
+autonomy    = "confirm"
+output      = "json"
+
+[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"
+
+[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"
+
+[reboot-host.args.delay-minutes]
+type        = "int"
+short       = "-d"
+description = "Minutes to wait before rebooting (0 = immediately)"
+default     = 0
+
 # ── TCP interfaces (nc-command) ────────────────────────────────────────────────
 
 [nc-command]

runspec_linux-0.3.0/runspec_linux/security.py

@@ -0,0 +1,24 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import last_logins, who
+
+
+def main_last_logins() -> None:
+    spec = rs.parse("last-logins")
+    limit = spec.limit.value
+    try:
+        print(json.dumps(last_logins(limit)))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_who() -> None:
+    rs.parse("who")
+    try:
+        print(json.dumps(who()))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux-0.3.0/runspec_linux/services.py

@@ -0,0 +1,40 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import check_service, list_services, restart_service
+from runspec_linux_core.errors import CommandError
+
+
+def main_check_service() -> None:
+    spec = rs.parse("check-service")
+    service = spec.service.value
+    try:
+        print(json.dumps(check_service(service)))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_list_services() -> None:
+    spec = rs.parse("list-services")
+    state_filter = spec.state.value
+    try:
+        print(json.dumps(list_services(state_filter)))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_restart_service() -> None:
+    spec = rs.parse("restart-service")
+    service = spec.service.value
+    try:
+        print(json.dumps(restart_service(service)))
+    except CommandError as e:
+        print(json.dumps({"service": service, "restarted": False, "error": str(e)}))
+        sys.exit(1)
+    except Exception as e:
+        # Includes ToolNotFoundError (systemctl absent).
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)