runspec-linux 0.1.0__py3-none-any.whl

runspec_linux/__init__.py

@@ -0,0 +1,3 @@
+from runspec_linux.nc_command import nc_send
+
+__all__ = ["nc_send"]

runspec_linux/containers.py

@@ -0,0 +1,117 @@
+import json
+import shutil
+import subprocess
+import sys
+
+import runspec as rs
+
+
+def _docker_available() -> bool:
+    return shutil.which("docker") is not None
+
+
+def main_list_containers() -> None:
+    spec = rs.parse("list-containers")
+    include_all = bool(spec.all)
+
+    if not _docker_available():
+        print(json.dumps({"error": "docker not installed or not in PATH"}))
+        sys.exit(1)
+
+    try:
+        cmd = [
+            "docker",
+            "ps",
+            "--format",
+            "{{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}\t{{.Names}}",
+        ]
+        if include_all:
+            cmd.append("--all")
+
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            print(json.dumps({"error": result.stderr.strip()}))
+            sys.exit(1)
+
+        rows = []
+        for line in result.stdout.strip().splitlines():
+            parts = line.split("\t")
+            if len(parts) < 6:
+                continue
+            rows.append(
+                {
+                    "id": parts[0],
+                    "image": parts[1],
+                    "command": parts[2].strip('"'),
+                    "created": parts[3],
+                    "status": parts[4],
+                    "name": parts[5],
+                }
+            )
+        print(json.dumps(rows))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_container_logs() -> None:
+    spec = rs.parse("container-logs")
+    container = str(spec.container)
+    lines = int(spec.lines)
+
+    if not _docker_available():
+        print(json.dumps({"error": "docker not installed or not in PATH"}))
+        sys.exit(1)
+
+    try:
+        result = subprocess.run(
+            ["docker", "logs", "--tail", str(lines), container],
+            capture_output=True,
+            text=True,
+        )
+        # docker logs writes to stderr by default
+        output = result.stderr if result.stderr else result.stdout
+        output_lines = output.strip().splitlines()
+        print(
+            json.dumps(
+                {
+                    "container": container,
+                    "lines": output_lines,
+                    "count": len(output_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 = str(spec.container)
+
+    if not _docker_available():
+        print(json.dumps({"error": "docker not installed or not in PATH"}))
+        sys.exit(1)
+
+    try:
+        result = subprocess.run(
+            ["docker", "restart", container],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            print(
+                json.dumps(
+                    {
+                        "container": container,
+                        "restarted": False,
+                        "error": result.stderr.strip(),
+                    }
+                )
+            )
+            sys.exit(1)
+        print(json.dumps({"container": container, "restarted": True}))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux/files.py

@@ -0,0 +1,72 @@
+import json
+import os
+import sys
+import tarfile
+from datetime import datetime
+from pathlib import Path
+
+import runspec as rs
+
+
+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)
+
+    min_bytes = int(min_mb * 1_048_576)
+
+    try:
+        results: list[dict] = []
+        for dirpath, _dirs, filenames in os.walk(search_path):
+            for name in filenames:
+                fpath = os.path.join(dirpath, name)
+                try:
+                    stat = os.stat(fpath, follow_symlinks=False)
+                    if stat.st_size >= min_bytes:
+                        results.append(
+                            {
+                                "path": fpath,
+                                "size_mb": round(stat.st_size / 1_048_576, 2),
+                                "modified": datetime.fromtimestamp(stat.st_mtime).strftime("%Y-%m-%d %H:%M:%S"),
+                            }
+                        )
+                except OSError:
+                    continue
+
+        results.sort(key=lambda r: r["size_mb"], reverse=True)
+        print(json.dumps(results[: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)
+    destination = str(spec.destination)
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    source_name = Path(source).name or "backup"
+    archive_name = f"{source_name}_{timestamp}.tar.gz"
+    archive_path = os.path.join(destination, archive_name)
+
+    try:
+        os.makedirs(destination, exist_ok=True)
+        with tarfile.open(archive_path, "w:gz") as tar:
+            tar.add(source, arcname=source_name)
+
+        size_bytes = os.path.getsize(archive_path)
+        print(
+            json.dumps(
+                {
+                    "source": source,
+                    "destination": archive_path,
+                    "size_bytes": size_bytes,
+                    "size_mb": round(size_bytes / 1_048_576, 2),
+                }
+            )
+        )
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux/logs.py

@@ -0,0 +1,81 @@
+import json
+import re
+import shutil
+import subprocess
+import sys
+
+import runspec as rs
+
+
+def main_tail_log() -> None:
+    spec = rs.parse("tail-log")
+    file_path = str(spec.file)
+    lines = int(spec.lines)
+
+    try:
+        with open(file_path, errors="replace") as f:
+            all_lines = f.readlines()
+        tail = [line.rstrip("\n") for line in all_lines[-lines:]]
+        print(json.dumps({"file": file_path, "lines": tail, "count": len(tail)}))
+    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)
+    pattern = str(spec.pattern)
+    limit = int(spec.limit)
+
+    try:
+        regex = re.compile(pattern, re.IGNORECASE)
+        matches: list[str] = []
+        with open(file_path, errors="replace") as f:
+            for line in f:
+                if regex.search(line):
+                    matches.append(line.rstrip("\n"))
+        trimmed = matches[-limit:] if len(matches) > limit else matches
+        print(
+            json.dumps(
+                {
+                    "file": file_path,
+                    "pattern": pattern,
+                    "matches": trimmed,
+                    "count": len(trimmed),
+                    "total_matches": len(matches),
+                }
+            )
+        )
+    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 = str(spec.unit)
+    lines = int(spec.lines)
+    since = str(spec.since) if spec.since is not None else None
+
+    if not shutil.which("journalctl"):
+        print(json.dumps({"error": "journalctl not available — not a systemd system"}))
+        sys.exit(1)
+
+    try:
+        cmd = ["journalctl", f"-u{unit}", f"-n{lines}", "--no-pager", "--output=short"]
+        if since:
+            cmd += [f"--since={since}"]
+
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        output_lines = result.stdout.strip().splitlines()
+        print(json.dumps({"unit": unit, "lines": output_lines, "count": len(output_lines)}))
+    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/nc_command.py

@@ -0,0 +1,65 @@
+import json
+import socket
+import sys
+import time
+
+import runspec as rs
+
+
+def nc_send(
+    host: str,
+    port: int,
+    command: str,
+    wait: float = 0.3,
+    read_timeout: float = 0.1,
+) -> str:
+    """Send a command over a plain TCP socket and return the response.
+
+    Appends a newline to command if not present, waits `wait` seconds for the
+    server to respond, then reads in chunks until the socket goes quiet.
+    """
+    with socket.create_connection((host, port), timeout=10) as sock:
+        payload = command if command.endswith("\n") else command + "\n"
+        sock.sendall(payload.encode())
+
+        time.sleep(wait)
+
+        sock.settimeout(read_timeout)
+        chunks: list[bytes] = []
+        while True:
+            try:
+                chunk = sock.recv(4096)
+                if not chunk:
+                    break
+                chunks.append(chunk)
+            except TimeoutError:
+                break
+
+    return b"".join(chunks).decode(errors="replace")
+
+
+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)
+
+    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/network.py

@@ -0,0 +1,159 @@
+import json
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import time
+
+import runspec as rs
+
+
+def main_ping_host() -> None:
+    spec = rs.parse("ping-host")
+    host = str(spec.host)
+    count = int(spec.count)
+
+    try:
+        result = subprocess.run(
+            ["ping", "-c", str(count), host],
+            capture_output=True,
+            text=True,
+        )
+        output = result.stdout + result.stderr
+
+        sent = received = 0
+        m = re.search(r"(\d+) packets transmitted,\s*(\d+) received", output)
+        if m:
+            sent = int(m.group(1))
+            received = int(m.group(2))
+
+        loss_pct = 0.0
+        m2 = re.search(r"([\d.]+)% packet loss", output)
+        if m2:
+            loss_pct = float(m2.group(1))
+
+        print(
+            json.dumps(
+                {
+                    "host": host,
+                    "reachable": received > 0,
+                    "packets_sent": sent,
+                    "packets_received": received,
+                    "loss_pct": loss_pct,
+                }
+            )
+        )
+    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 = str(spec.host)
+    port = int(spec.port)
+    timeout = float(spec.timeout)
+
+    start = time.monotonic()
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            elapsed_ms = round((time.monotonic() - start) * 1000, 1)
+            print(
+                json.dumps(
+                    {
+                        "host": host,
+                        "port": port,
+                        "open": True,
+                        "response_ms": elapsed_ms,
+                    }
+                )
+            )
+    except (OSError, TimeoutError):
+        elapsed_ms = round((time.monotonic() - start) * 1000, 1)
+        print(json.dumps({"host": host, "port": port, "open": False, "response_ms": elapsed_ms}))
+
+
+def main_show_connections() -> None:
+    spec = rs.parse("show-connections")
+    state_filter = str(spec.state)
+
+    try:
+        if shutil.which("ss"):
+            cmd = ["ss", "-tupn"]
+            result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+            rows = _parse_ss(result.stdout, state_filter)
+        elif shutil.which("netstat"):
+            cmd = ["netstat", "-tupn"]
+            result = subprocess.run(cmd, capture_output=True, text=True)
+            rows = _parse_netstat(result.stdout, state_filter)
+        else:
+            print(json.dumps({"error": "Neither ss nor netstat found in PATH"}))
+            sys.exit(1)
+
+        print(json.dumps(rows))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def _parse_ss(output: str, state_filter: str) -> list[dict]:
+    rows = []
+    for line in output.strip().splitlines()[1:]:
+        parts = line.split()
+        if len(parts) < 5:
+            continue
+        proto, local, peer = parts[0], parts[3], parts[4]
+        state = parts[5] if len(parts) > 5 and not parts[5].startswith("users:") else ""
+        process = ""
+        for p in parts:
+            if p.startswith("users:"):
+                m = re.search(r'"([^"]+)"', p)
+                if m:
+                    process = m.group(1)
+
+        row_state = state.lower() if state else ("listen" if peer == "*:*" else "established")
+        if state_filter == "established" and "estab" not in row_state:
+            continue
+        if state_filter == "listening" and "listen" not in row_state:
+            continue
+
+        rows.append(
+            {
+                "proto": proto,
+                "local": local,
+                "peer": peer,
+                "state": state,
+                "process": process,
+            }
+        )
+    return rows
+
+
+def _parse_netstat(output: str, state_filter: str) -> list[dict]:
+    rows = []
+    for line in output.strip().splitlines():
+        parts = line.split()
+        if not parts or parts[0] not in ("tcp", "tcp6", "udp", "udp6"):
+            continue
+        if len(parts) < 6:
+            continue
+        proto, local, foreign = parts[0], parts[3], parts[4]
+        state = parts[5] if len(parts) > 5 else ""
+        process = parts[-1] if len(parts) > 6 else ""
+
+        if state_filter == "established" and state.upper() != "ESTABLISHED":
+            continue
+        if state_filter == "listening" and state.upper() != "LISTEN":
+            continue
+
+        rows.append(
+            {
+                "proto": proto,
+                "local": local,
+                "peer": foreign,
+                "state": state,
+                "process": process,
+            }
+        )
+    return rows

runspec_linux/runspec.toml

@@ -0,0 +1,328 @@
+[config]
+autonomy-default = "autonomous"
+
+# ── System monitoring ─────────────────────────────────────────────────────────
+
+[system-info]
+serve     = ["local"]
+description = "Report hostname, OS, kernel version, uptime, load averages, and CPU count"
+autonomy  = "autonomous"
+output    = "json"
+
+[disk-usage]
+serve     = ["local"]
+description = "Report disk usage for all mounted filesystems"
+autonomy  = "autonomous"
+output    = "json"
+
+[check-memory]
+serve     = ["local"]
+description = "Report RAM and swap usage in megabytes"
+autonomy  = "autonomous"
+output    = "json"
+
+[list-processes]
+serve     = ["local"]
+description = "List running processes, optionally filtered by name"
+autonomy  = "autonomous"
+output    = "json"
+
+[list-processes.args.filter]
+type        = "str"
+short       = "-f"
+description = "Filter processes whose command contains this string"
+required    = false
+
+[list-processes.args.limit]
+type        = "int"
+short       = "-n"
+description = "Maximum number of processes to return"
+default     = 20
+
+# ── Services ──────────────────────────────────────────────────────────────────
+
+[check-service]
+serve       = ["local"]
+description = "Check whether a systemd service is active and report its status"
+autonomy    = "autonomous"
+output      = "json"
+
+[check-service.args.service]
+type        = "str"
+short       = "-s"
+description = "Service name (e.g. nginx or nginx.service)"
+
+[list-services]
+serve       = ["local"]
+description = "List all systemd service units and their active/sub state"
+autonomy    = "autonomous"
+output      = "json"
+
+[list-services.args.state]
+type        = "choice"
+options     = ["all", "active", "failed", "inactive"]
+default     = "all"
+description = "Filter services by active state"
+
+[restart-service]
+serve       = ["local"]
+description = "Restart a systemd service"
+autonomy    = "confirm"
+output      = "json"
+
+[restart-service.args.service]
+type        = "str"
+short       = "-s"
+description = "Service name to restart"
+
+# ── Logs ──────────────────────────────────────────────────────────────────────
+
+[tail-log]
+serve       = ["local"]
+description = "Return the last N lines of a log file"
+autonomy    = "autonomous"
+output      = "json"
+
+[tail-log.args.file]
+type        = "path"
+short       = "-f"
+description = "Path to the log file"
+
+[tail-log.args.lines]
+type        = "int"
+short       = "-n"
+description = "Number of lines to return"
+default     = 50
+
+[search-log]
+serve       = ["local"]
+description = "Search a log file for lines matching a pattern"
+autonomy    = "autonomous"
+output      = "json"
+
+[search-log.args.file]
+type        = "path"
+short       = "-f"
+description = "Path to the log file"
+
+[search-log.args.pattern]
+type        = "str"
+short       = "-p"
+description = "Search pattern (case-insensitive substring or regex)"
+
+[search-log.args.limit]
+type        = "int"
+short       = "-n"
+description = "Maximum number of matching lines to return"
+default     = 100
+
+[journalctl]
+serve       = ["local"]
+description = "Fetch recent journal entries for a systemd unit (systemd-only)"
+autonomy    = "autonomous"
+output      = "json"
+
+[journalctl.args.unit]
+type        = "str"
+short       = "-u"
+description = "Systemd unit name (e.g. nginx or nginx.service)"
+
+[journalctl.args.lines]
+type        = "int"
+short       = "-n"
+description = "Number of lines to return"
+default     = 50
+
+[journalctl.args.since]
+type        = "str"
+description = "Return entries since this time string (e.g. '1 hour ago', '2026-05-27 08:00')"
+required    = false
+
+# ── Network ───────────────────────────────────────────────────────────────────
+
+[ping-host]
+serve       = ["local"]
+description = "Ping a host and report reachability and packet loss"
+autonomy    = "autonomous"
+output      = "json"
+
+[ping-host.args.host]
+type        = "str"
+short       = "-H"
+description = "Hostname or IP address to ping"
+
+[ping-host.args.count]
+type        = "int"
+short       = "-c"
+description = "Number of ICMP packets to send"
+default     = 4
+
+[check-port]
+serve       = ["local"]
+description = "Check whether a TCP port is open on a host"
+autonomy    = "autonomous"
+output      = "json"
+
+[check-port.args.host]
+type        = "str"
+short       = "-H"
+description = "Hostname or IP address"
+
+[check-port.args.port]
+type        = "int"
+short       = "-p"
+description = "TCP port number"
+
+[check-port.args.timeout]
+type        = "float"
+description = "Connection timeout in seconds"
+default     = 3.0
+
+[show-connections]
+serve       = ["local"]
+description = "Show active TCP/UDP connections (equivalent to ss or netstat)"
+autonomy    = "autonomous"
+output      = "json"
+
+[show-connections.args.state]
+type        = "choice"
+options     = ["all", "established", "listening"]
+default     = "all"
+description = "Filter connections by state"
+
+# ── Files ─────────────────────────────────────────────────────────────────────
+
+[find-large-files]
+serve       = ["local"]
+description = "Find files larger than a threshold in a directory tree"
+autonomy    = "autonomous"
+output      = "json"
+
+[find-large-files.args.path]
+type        = "path"
+short       = "-p"
+description = "Directory to search"
+
+[find-large-files.args.min-mb]
+type        = "float"
+description = "Minimum file size in megabytes"
+default     = 100.0
+
+[find-large-files.args.limit]
+type        = "int"
+short       = "-n"
+description = "Maximum number of results to return (sorted by size, largest first)"
+default     = 20
+
+[backup-files]
+serve       = ["local"]
+description = "Create a timestamped tar.gz archive of a directory"
+autonomy    = "confirm"
+output      = "json"
+
+[backup-files.args.source]
+type        = "path"
+short       = "-s"
+description = "Directory to archive"
+
+[backup-files.args.destination]
+type        = "path"
+short       = "-d"
+description = "Directory where the archive will be written"
+default     = "/tmp"
+
+# ── Security ──────────────────────────────────────────────────────────────────
+
+[last-logins]
+serve       = ["local"]
+description = "Show recent login history from the wtmp log"
+autonomy    = "autonomous"
+output      = "json"
+
+[last-logins.args.limit]
+type        = "int"
+short       = "-n"
+description = "Number of login records to return"
+default     = 20
+
+[who]
+serve       = ["local"]
+description = "List users currently logged in to the system"
+autonomy    = "autonomous"
+output      = "json"
+
+# ── Containers ────────────────────────────────────────────────────────────────
+
+[list-containers]
+serve       = ["local"]
+description = "List Docker containers (requires Docker)"
+autonomy    = "autonomous"
+output      = "json"
+
+[list-containers.args.all]
+type        = "flag"
+short       = "-a"
+description = "Include stopped containers"
+default     = false
+
+[container-logs]
+serve       = ["local"]
+description = "Fetch recent log output from a Docker container"
+autonomy    = "autonomous"
+output      = "json"
+
+[container-logs.args.container]
+type        = "str"
+short       = "-c"
+description = "Container name or ID"
+
+[container-logs.args.lines]
+type        = "int"
+short       = "-n"
+description = "Number of lines to return"
+default     = 50
+
+[restart-container]
+serve       = ["local"]
+description = "Restart a Docker container"
+autonomy    = "confirm"
+output      = "json"
+
+[restart-container.args.container]
+type        = "str"
+short       = "-c"
+description = "Container name or ID"
+
+# ── TCP interfaces (nc-command) ────────────────────────────────────────────────
+
+[nc-command]
+serve       = ["local"]
+description = "Send a command over a plain TCP socket and return the response (nc-style)"
+autonomy    = "autonomous"
+output      = "json"
+
+[nc-command.args.host]
+type        = "str"
+short       = "-H"
+description = "Hostname or IP address"
+
+[nc-command.args.port]
+type        = "int"
+short       = "-p"
+description = "TCP port number"
+
+[nc-command.args.command]
+type        = "str"
+short       = "-c"
+description = "Command string to send (a newline is appended automatically)"
+
+[nc-command.args.wait]
+type        = "float"
+short       = "-w"
+description = "Seconds to keep the connection open after sending (allows server response to arrive)"
+default     = 0.3
+
+[nc-command.args.read-timeout]
+type        = "float"
+description = "Per-chunk socket read timeout in seconds"
+default     = 0.1

runspec_linux/security.py

@@ -0,0 +1,70 @@
+import json
+import shutil
+import subprocess
+import sys
+
+import runspec as rs
+
+
+def main_last_logins() -> None:
+    spec = rs.parse("last-logins")
+    limit = int(spec.limit)
+
+    if not shutil.which("last"):
+        print(json.dumps({"error": "last command not found"}))
+        sys.exit(1)
+
+    try:
+        result = subprocess.run(
+            ["last", "-n", str(limit), "--time-format", "iso"],
+            capture_output=True,
+            text=True,
+        )
+        rows = []
+        for line in result.stdout.strip().splitlines():
+            if not line or line.startswith("wtmp") or line.startswith("btmp"):
+                continue
+            parts = line.split()
+            if len(parts) < 3:
+                continue
+            rows.append(
+                {
+                    "user": parts[0],
+                    "terminal": parts[1],
+                    "from": parts[2] if len(parts) > 2 else "",
+                    "login_time": parts[3] if len(parts) > 3 else "",
+                    "logout_time": parts[5] if len(parts) > 5 else "",
+                }
+            )
+        print(json.dumps(rows[:limit]))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_who() -> None:
+    rs.parse("who")
+
+    if not shutil.which("who"):
+        print(json.dumps({"error": "who command not found"}))
+        sys.exit(1)
+
+    try:
+        result = subprocess.run(["who"], capture_output=True, text=True, check=True)
+        rows = []
+        for line in result.stdout.strip().splitlines():
+            parts = line.split()
+            if len(parts) < 3:
+                continue
+            rows.append(
+                {
+                    "user": parts[0],
+                    "terminal": parts[1],
+                    "login_time": " ".join(parts[2:4]) if len(parts) > 3 else parts[2],
+                    "from": parts[4].strip("()") if len(parts) > 4 else "",
+                }
+            )
+        print(json.dumps(rows))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux/services.py

@@ -0,0 +1,119 @@
+import json
+import shutil
+import subprocess
+import sys
+
+import runspec as rs
+
+
+def _systemctl_available() -> bool:
+    return shutil.which("systemctl") is not None
+
+
+def main_check_service() -> None:
+    spec = rs.parse("check-service")
+    service = str(spec.service)
+
+    if not _systemctl_available():
+        print(json.dumps({"error": "systemctl not available — not a systemd system"}))
+        sys.exit(1)
+
+    try:
+        result = subprocess.run(
+            [
+                "systemctl",
+                "show",
+                service,
+                "--property=ActiveState,SubState,LoadState,Description,ActiveEnterTimestamp",
+            ],
+            capture_output=True,
+            text=True,
+        )
+        props: dict[str, str] = {}
+        for line in result.stdout.strip().splitlines():
+            if "=" in line:
+                k, v = line.split("=", 1)
+                props[k] = v
+
+        active = props.get("ActiveState", "unknown")
+        print(
+            json.dumps(
+                {
+                    "service": service,
+                    "active": active == "active",
+                    "active_state": active,
+                    "sub_state": props.get("SubState", "unknown"),
+                    "load_state": props.get("LoadState", "unknown"),
+                    "description": props.get("Description", ""),
+                    "since": props.get("ActiveEnterTimestamp", ""),
+                }
+            )
+        )
+    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 = str(spec.state)
+
+    if not _systemctl_available():
+        print(json.dumps({"error": "systemctl not available — not a systemd system"}))
+        sys.exit(1)
+
+    try:
+        cmd = ["systemctl", "list-units", "--type=service", "--no-pager", "--no-legend"]
+        if state_filter != "all":
+            cmd += [f"--state={state_filter}"]
+
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        rows = []
+        for line in result.stdout.strip().splitlines():
+            parts = line.split(None, 4)
+            if len(parts) < 4:
+                continue
+            rows.append(
+                {
+                    "unit": parts[0],
+                    "load": parts[1],
+                    "active": parts[2],
+                    "sub": parts[3],
+                    "description": parts[4] if len(parts) > 4 else "",
+                }
+            )
+        print(json.dumps(rows))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_restart_service() -> None:
+    spec = rs.parse("restart-service")
+    service = str(spec.service)
+
+    if not _systemctl_available():
+        print(json.dumps({"error": "systemctl not available — not a systemd system"}))
+        sys.exit(1)
+
+    try:
+        result = subprocess.run(
+            ["systemctl", "restart", service],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            print(
+                json.dumps(
+                    {
+                        "service": service,
+                        "restarted": False,
+                        "error": result.stderr.strip(),
+                    }
+                )
+            )
+            sys.exit(1)
+        print(json.dumps({"service": service, "restarted": True}))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux/system_info.py

@@ -0,0 +1,140 @@
+import json
+import os
+import platform
+import sys
+
+import runspec as rs
+
+
+def main_system_info() -> None:
+    rs.parse("system-info")
+
+    try:
+        load1, load5, load15 = os.getloadavg()
+        with open("/proc/uptime") as f:
+            uptime_seconds = float(f.read().split()[0])
+
+        print(
+            json.dumps(
+                {
+                    "hostname": platform.node(),
+                    "os": f"{platform.system()} {platform.release()}",
+                    "kernel": platform.version(),
+                    "machine": platform.machine(),
+                    "uptime_seconds": round(uptime_seconds),
+                    "load_1": round(load1, 2),
+                    "load_5": round(load5, 2),
+                    "load_15": round(load15, 2),
+                    "cpu_count": os.cpu_count(),
+                }
+            )
+        )
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_disk_usage() -> None:
+    rs.parse("disk-usage")
+
+    try:
+        import subprocess
+
+        result = subprocess.run(
+            ["df", "-P", "-B1"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        rows = []
+        for line in result.stdout.strip().splitlines()[1:]:
+            parts = line.split()
+            if len(parts) < 6:
+                continue
+            size_bytes = int(parts[1])
+            used_bytes = int(parts[2])
+            avail_bytes = int(parts[3])
+            rows.append(
+                {
+                    "filesystem": parts[0],
+                    "size_mb": round(size_bytes / 1_048_576, 1),
+                    "used_mb": round(used_bytes / 1_048_576, 1),
+                    "available_mb": round(avail_bytes / 1_048_576, 1),
+                    "use_pct": parts[4],
+                    "mounted_on": parts[5],
+                }
+            )
+        print(json.dumps(rows))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_check_memory() -> None:
+    rs.parse("check-memory")
+
+    try:
+        mem: dict[str, int] = {}
+        with open("/proc/meminfo") as f:
+            for line in f:
+                key, val_kb = line.split(":")
+                kb = int(val_kb.strip().split()[0])
+                mem[key.strip()] = kb
+
+        print(
+            json.dumps(
+                {
+                    "total_mb": round(mem.get("MemTotal", 0) / 1024, 1),
+                    "used_mb": round((mem.get("MemTotal", 0) - mem.get("MemAvailable", 0)) / 1024, 1),
+                    "free_mb": round(mem.get("MemFree", 0) / 1024, 1),
+                    "available_mb": round(mem.get("MemAvailable", 0) / 1024, 1),
+                    "cached_mb": round(mem.get("Cached", 0) / 1024, 1),
+                    "swap_total_mb": round(mem.get("SwapTotal", 0) / 1024, 1),
+                    "swap_used_mb": round((mem.get("SwapTotal", 0) - mem.get("SwapFree", 0)) / 1024, 1),
+                }
+            )
+        )
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+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)
+
+    try:
+        import subprocess
+
+        result = subprocess.run(
+            ["ps", "aux", "--no-headers"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        rows = []
+        for line in result.stdout.strip().splitlines():
+            parts = line.split(None, 10)
+            if len(parts) < 11:
+                continue
+            command = parts[10]
+            if name_filter and name_filter.lower() not in command.lower():
+                continue
+            rows.append(
+                {
+                    "user": parts[0],
+                    "pid": int(parts[1]),
+                    "cpu_pct": float(parts[2]),
+                    "mem_pct": float(parts[3]),
+                    "vsz_kb": int(parts[4]),
+                    "rss_kb": int(parts[5]),
+                    "stat": parts[7],
+                    "command": command,
+                }
+            )
+        rows.sort(key=lambda r: r["cpu_pct"], reverse=True)
+        print(json.dumps(rows[:limit]))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

runspec_linux-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: runspec-linux
+Version: 0.1.0
+Summary: Linux system admin runnables for runspec
+Requires-Python: >=3.11
+Requires-Dist: runspec>=0.17.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

runspec_linux-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+runspec_linux/__init__.py,sha256=4Ip3UjHGdqM7G8KUd9Z0M-DU89a1S0UWZCy0mrvT3MA,68
+runspec_linux/containers.py,sha256=aNx6F9Wsaw7MEezRLr9UrS8_DxFsPO7LLO82qLycOdY,3279
+runspec_linux/files.py,sha256=Dx6SmewG0LIvTVRedZnCET31TM7OKVWeviWrJrxjUgc,2257
+runspec_linux/logs.py,sha256=QQeQT8hbLxKrVzv9myPoZW6H3CjQw--t3WL_nhy031E,2562
+runspec_linux/nc_command.py,sha256=32X7IGrXq6lF3Xuvgy9wW5SqhUT7wC_FGeDkljEtySs,1733
+runspec_linux/network.py,sha256=YrkQc9ISODnNUytaRYyW3ptNzFfcdxhgFxGwNiAcNG8,4750
+runspec_linux/runspec.toml,sha256=IllfzWlJ9lFx_QhyMARAYLjkaAh-Zkzum_rn5Bt3dR0,9289
+runspec_linux/security.py,sha256=Zy6fKLLCZXgcIQoenxcetNWsHNZxMbsJhR0x-87FLO8,2085
+runspec_linux/services.py,sha256=tjZjaVLuHKS4EN9l0vKRjymfLpgvJ0t6AIpZivF71MI,3565
+runspec_linux/system_info.py,sha256=CN2E_hiHeZG-BobfSCpqsFNRu_uKlp4SQgRsN084_M4,4399
+runspec_linux-0.1.0.dist-info/METADATA,sha256=mkwJ0DZygQEPJD8vlz6Q85rPXWVC6YyNNwxDdcLyNE8,297
+runspec_linux-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+runspec_linux-0.1.0.dist-info/entry_points.txt,sha256=_QpmTRGmjww1oJ7Ze8kl63x-_fZycJPQGf0V7Jxu8EQ,1176
+runspec_linux-0.1.0.dist-info/RECORD,,

runspec_linux-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

runspec_linux-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,22 @@
+[console_scripts]
+backup-files = runspec_linux.files:main_backup_files
+check-memory = runspec_linux.system_info:main_check_memory
+check-port = runspec_linux.network:main_check_port
+check-service = runspec_linux.services:main_check_service
+container-logs = runspec_linux.containers:main_container_logs
+disk-usage = runspec_linux.system_info:main_disk_usage
+find-large-files = runspec_linux.files:main_find_large_files
+journalctl = runspec_linux.logs:main_journalctl
+last-logins = runspec_linux.security:main_last_logins
+list-containers = runspec_linux.containers:main_list_containers
+list-processes = runspec_linux.system_info:main_list_processes
+list-services = runspec_linux.services:main_list_services
+nc-command = runspec_linux.nc_command:main
+ping-host = runspec_linux.network:main_ping_host
+restart-container = runspec_linux.containers:main_restart_container
+restart-service = runspec_linux.services:main_restart_service
+search-log = runspec_linux.logs:main_search_log
+show-connections = runspec_linux.network:main_show_connections
+system-info = runspec_linux.system_info:main_system_info
+tail-log = runspec_linux.logs:main_tail_log
+who = runspec_linux.security:main_who