runspec-linux 0.1.0__tar.gz

runspec_linux-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# 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/

runspec_linux-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# runspec-linux Changelog
+
+## [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.0/PKG-INFO

@@ -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/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-linux"
+version = "0.1.0"
+requires-python = ">=3.11"
+description = "Linux system admin runnables for runspec"
+dependencies = [
+    "runspec>=0.17.0",
+]
+
+[project.scripts]
+system-info       = "runspec_linux.system_info:main_system_info"
+disk-usage        = "runspec_linux.system_info:main_disk_usage"
+check-memory      = "runspec_linux.system_info:main_check_memory"
+list-processes    = "runspec_linux.system_info:main_list_processes"
+check-service     = "runspec_linux.services:main_check_service"
+list-services     = "runspec_linux.services:main_list_services"
+restart-service   = "runspec_linux.services:main_restart_service"
+tail-log          = "runspec_linux.logs:main_tail_log"
+search-log        = "runspec_linux.logs:main_search_log"
+journalctl        = "runspec_linux.logs:main_journalctl"
+ping-host         = "runspec_linux.network:main_ping_host"
+check-port        = "runspec_linux.network:main_check_port"
+show-connections  = "runspec_linux.network:main_show_connections"
+find-large-files  = "runspec_linux.files:main_find_large_files"
+backup-files      = "runspec_linux.files:main_backup_files"
+last-logins       = "runspec_linux.security:main_last_logins"
+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"
+nc-command        = "runspec_linux.nc_command:main"
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.11"
+
+[tool.ruff]
+line-length = 200
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_linux-0.1.0/runspec_linux/__init__.py

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

runspec_linux-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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