runspec-linux-core 0.4.0__tar.gz → 0.6.0__tar.gz

{runspec_linux_core-0.4.0 → runspec_linux_core-0.6.0}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # runspec-linux-core Changelog
 
+## [0.6.0] — 2026-08-24
+
+New `runspec_linux_core.cron` module — pure helpers for managing a user's
+crontab: `list_cron`, `add_cron`, `remove_cron`, `clear_cron`, plus the
+`validate_schedule` shape check. Each takes the same keyword-only `run_as` /
+`become_method` escalation as the container/venv helpers and wraps its
+`crontab` subprocess with `build_become`, so "run as `bob`" reads/writes
+`bob`'s own crontab (`sudo -n -u bob crontab -l` / `crontab -`); with no
+`run_as` the caller's crontab is used. Editing is a read-modify-write (crontab
+has no append/delete verbs): the whole new table is piped to `crontab -`.
+`list_cron` returns structured job records (schedule, command, an attached
+`# comment`, `special` for `@nickname` schedules) plus environment
+assignments; a user with no crontab is reported `exists: false`, not an error.
+`add_cron` is idempotent (an identical `schedule command` line is left as-is
+unless `allow_duplicate`); `remove_cron` selects by command `match` or job
+`index` and drops a preceding `# comment` line with the job. Schedules,
+commands, and comments are guarded against newline injection. Failures raise
+`ToolNotFoundError` (no `crontab`), `CommandError` (non-zero subprocess, with
+the passwordless-sudo hint), or `ValueError` (bad input).
+
+
+## [0.5.0] — 2026-08-07
+
+The Docker container helpers now take the same per-invocation `run_as` /
+`become_method` escalation as the log/service helpers, since the Docker daemon
+socket is typically root- or `docker`-group-owned. `list_containers`,
+`container_logs`, and `restart_container` gain keyword-only `run_as` /
+`become_method` params and wrap their `docker` subprocess with `build_become`;
+a failed escalated command raises `CommandError` with the passwordless-sudo hint
+(`container_logs` no longer returns the sudo error as log lines when `run_as` is
+set). No behaviour change when `run_as` is unset.
+
+
 ## [0.4.0] — 2026-08-01
 
 New shared privilege-escalation module `runspec_linux_core.become` — the single

{runspec_linux_core-0.4.0 → runspec_linux_core-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: runspec-linux-core
-Version: 0.4.0
+Version: 0.6.0
 Summary: Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)
 Requires-Python: >=3.10
 Provides-Extra: dev

{runspec_linux_core-0.4.0 → runspec_linux_core-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux-core"
-version = "0.4.0"
+version = "0.6.0"
 requires-python = ">=3.10"
 description = "Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)"
 dependencies = []

{runspec_linux_core-0.4.0 → runspec_linux_core-0.6.0}/runspec_linux_core/__init__.py

@@ -23,6 +23,13 @@ from runspec_linux_core.containers import (
     list_containers,
     restart_container,
 )
+from runspec_linux_core.cron import (
+    add_cron,
+    clear_cron,
+    list_cron,
+    remove_cron,
+    validate_schedule,
+)
 from runspec_linux_core.errors import CommandError, LinuxCoreError, ToolNotFoundError
 from runspec_linux_core.files import backup_files, find_large_files
 from runspec_linux_core.investigate import (
@@ -111,6 +118,12 @@ __all__ = [
     "list_containers",
     "container_logs",
     "restart_container",
+    # cron
+    "list_cron",
+    "add_cron",
+    "remove_cron",
+    "clear_cron",
+    "validate_schedule",
     # packages
     "detect_manager",
     "list_packages",

runspec_linux_core-0.6.0/runspec_linux_core/containers.py

@@ -0,0 +1,102 @@
+"""Docker container helpers: list, logs, restart.
+
+The Docker daemon socket is typically root-owned (or restricted to the ``docker``
+group), so each helper takes an optional ``run_as`` user (with a
+``become_method``). When set, the ``docker`` command is escalated via
+``sudo -n -u`` / ``su`` (:func:`runspec_linux_core.become.build_become`) — a
+``--sudo`` flag on the runnable maps to ``run_as="root"``. With no ``run_as`` the
+command runs as the calling user (unchanged).
+"""
+
+import shutil
+import subprocess
+
+from runspec_linux_core.become import build_become, check_become_error
+from runspec_linux_core.errors import ToolNotFoundError
+
+
+def _docker_available() -> bool:
+    return shutil.which("docker") is not None
+
+
+def list_containers(include_all: bool = False, *, run_as: str | None = None, become_method: str = "sudo") -> list[dict]:
+    """Return Docker containers (running, or all if ``include_all``).
+
+    Raises ToolNotFoundError if docker is not installed, or CommandError if the
+    ``docker ps`` command returns a non-zero exit (with a passwordless-sudo hint
+    when ``run_as`` is set).
+    """
+    if not _docker_available():
+        raise ToolNotFoundError("docker not installed or not in PATH")
+
+    cmd = [
+        "docker",
+        "ps",
+        "--format",
+        "{{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}\t{{.Names}}",
+    ]
+    if include_all:
+        cmd.append("--all")
+
+    result = subprocess.run(build_become(cmd, run_as, become_method), capture_output=True, text=True)
+    if result.returncode != 0:
+        check_become_error("list containers", result.stderr, run_as)
+
+    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],
+            }
+        )
+    return rows
+
+
+def container_logs(container: str, lines: int = 50, *, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """Return the last ``lines`` log lines for a container.
+
+    Raises ToolNotFoundError if docker is not installed. When ``run_as`` is set
+    and the escalated command fails, raises CommandError with a passwordless-sudo
+    hint rather than returning the sudo error as log lines.
+    """
+    if not _docker_available():
+        raise ToolNotFoundError("docker not installed or not in PATH")
+
+    argv = build_become(["docker", "logs", "--tail", str(lines), container], run_as, become_method)
+    result = subprocess.run(argv, capture_output=True, text=True)
+    if run_as and result.returncode != 0:
+        check_become_error("container logs", result.stderr, run_as)
+    # docker logs writes to stderr by default
+    output = result.stderr if result.stderr else result.stdout
+    output_lines = output.strip().splitlines()
+    out = {"container": container, "lines": output_lines, "count": len(output_lines)}
+    if run_as:
+        out["run_as"] = run_as
+    return out
+
+
+def restart_container(container: str, *, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """Restart a container. Returns ``{container, restarted: True}`` on success.
+
+    Raises ToolNotFoundError if docker is not installed, or CommandError if the
+    restart returns a non-zero exit (with a passwordless-sudo hint when
+    ``run_as`` is set).
+    """
+    if not _docker_available():
+        raise ToolNotFoundError("docker not installed or not in PATH")
+
+    result = subprocess.run(build_become(["docker", "restart", container], run_as, become_method), capture_output=True, text=True)
+    if result.returncode != 0:
+        check_become_error("restart container", result.stderr, run_as)
+    out = {"container": container, "restarted": True}
+    if run_as:
+        out["run_as"] = run_as
+    return out

runspec_linux_core-0.6.0/runspec_linux_core/cron.py

@@ -0,0 +1,368 @@
+"""Cron (per-user crontab) management: list, add, remove, clear jobs.
+
+Every helper drives the ``crontab`` binary and manages **one user's crontab**.
+Which user is chosen *per invocation* via the shared ``run_as`` escalation
+(mechanism B, like the venv/container helpers): with ``run_as`` set, the
+``crontab`` command is wrapped in ``sudo -n -u <user>`` / ``su <user> -c`` by
+:func:`runspec_linux_core.become.build_become`, so ``crontab -l`` reads and
+``crontab -`` writes *that user's* own crontab. With no ``run_as`` the caller's
+own crontab is used. ``-n`` makes sudo fail fast instead of hanging on the
+TTY-less SSH channel; passwordless sudo is assumed (see ``enable-passwordless-sudo``).
+
+Editing a crontab is a read-modify-write: ``crontab -l`` to read the current
+table, then the whole new table is piped to ``crontab -`` (crontab has no
+append/delete verbs of its own). Schedules, commands, and comments are guarded
+against newline injection so a crafted value can't smuggle extra crontab lines.
+
+Each function returns plain data and raises on failure (``ToolNotFoundError``
+when ``crontab`` is absent, ``CommandError`` for a non-zero subprocess,
+``ValueError`` for bad input). The thin ``runspec-linux`` wrappers render the
+JSON/exit.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+
+from runspec_linux_core.become import build_become, check_become_error, current_user
+from runspec_linux_core.errors import ToolNotFoundError
+
+# The nickname schedules cron accepts in place of the 5 time fields.
+_SPECIALS = frozenset(
+    {
+        "@reboot",
+        "@yearly",
+        "@annually",
+        "@monthly",
+        "@weekly",
+        "@daily",
+        "@midnight",
+        "@hourly",
+    }
+)
+
+# Characters allowed in a single cron time field (digits, ``*``, ranges, steps,
+# lists, and month/day-of-week names). Deliberately permissive — cron itself is
+# the final arbiter of a field's meaning; this only rejects obvious garbage and
+# stray whitespace so we don't write a malformed table.
+_FIELD_RE = re.compile(r"^[0-9*/,\-A-Za-z]+$")
+
+# An environment assignment line in a crontab (``NAME=value``), as cron treats it.
+_ENV_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$")
+
+
+def _crontab_available() -> bool:
+    return shutil.which("crontab") is not None
+
+
+def _no_such_crontab(stderr: str) -> bool:
+    """True when ``crontab -l`` failed only because the user has no crontab yet
+    (an empty table, not a real error)."""
+    return "no crontab for" in stderr.lower()
+
+
+def _reject_newline(value: str, what: str) -> str:
+    if "\n" in value or "\r" in value:
+        raise ValueError(f"{what} must not contain a newline")
+    return value
+
+
+def validate_schedule(schedule: str) -> str:
+    """Return ``schedule`` unchanged if it is a well-formed cron schedule — a
+    recognised ``@nickname`` or exactly five whitespace-separated time fields —
+    else raise :class:`ValueError`.
+
+    This is a shape check, not a full semantic validation: each field only has to
+    use cron's grammar characters. crontab itself rejects out-of-range values.
+    """
+    _reject_newline(schedule, "schedule")
+    text = schedule.strip()
+    if not text:
+        raise ValueError("empty schedule")
+    if text.startswith("@"):
+        if text.lower() not in _SPECIALS:
+            raise ValueError(f"unknown schedule nickname: {text!r} (expected one of {', '.join(sorted(_SPECIALS))})")
+        return text.lower()
+    fields = text.split()
+    if len(fields) != 5:
+        raise ValueError(f"schedule needs 5 fields (min hour day-of-month month day-of-week) or an @nickname; got {len(fields)}: {text!r}")
+    for field in fields:
+        if not _FIELD_RE.match(field):
+            raise ValueError(f"invalid character in schedule field {field!r}")
+    return " ".join(fields)
+
+
+def _parse_line(line: str) -> dict:
+    """Classify one crontab line into a typed record (job / special / env /
+    comment / blank / unknown). Job/special records carry ``schedule`` +
+    ``command``; the caller stitches on any preceding comment."""
+    stripped = line.strip()
+    if not stripped:
+        return {"kind": "blank"}
+    if stripped.startswith("#"):
+        return {"kind": "comment", "text": stripped.lstrip("#").strip(), "raw": line}
+    if stripped.startswith("@"):
+        parts = stripped.split(None, 1)
+        nickname = parts[0].lower()
+        if nickname in _SPECIALS and len(parts) == 2:
+            return {"kind": "special", "schedule": nickname, "command": parts[1], "raw": line}
+        return {"kind": "unknown", "raw": line}
+    env = _ENV_RE.match(stripped)
+    if env:
+        return {"kind": "env", "name": env.group(1), "value": env.group(2).strip(), "raw": line}
+    parts = stripped.split(None, 5)
+    if len(parts) == 6:
+        return {"kind": "job", "schedule": " ".join(parts[:5]), "command": parts[5], "raw": line}
+    return {"kind": "unknown", "raw": line}
+
+
+def _read_crontab(run_as: str | None, become_method: str) -> tuple[list[str], bool]:
+    """Return ``(lines, exists)`` for the target user's current crontab.
+
+    ``exists`` is False (and ``lines`` empty) when the user simply has no crontab
+    yet — that is the normal empty state, not an error. Raises CommandError on a
+    real ``crontab -l`` failure (with a passwordless-sudo hint when escalating).
+    """
+    result = subprocess.run(build_become(["crontab", "-l"], run_as, become_method), capture_output=True, text=True)
+    if result.returncode != 0:
+        if _no_such_crontab(result.stderr):
+            return [], False
+        check_become_error("read crontab", result.stderr, run_as)
+    return result.stdout.splitlines(), True
+
+
+def _write_crontab(lines: list[str], run_as: str | None, become_method: str) -> None:
+    """Install ``lines`` as the target user's whole crontab via ``crontab -``.
+    Raises CommandError on failure (with a passwordless-sudo hint when escalating)."""
+    content = "\n".join(lines)
+    if content and not content.endswith("\n"):
+        content += "\n"
+    result = subprocess.run(
+        build_become(["crontab", "-"], run_as, become_method),
+        input=content,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        check_become_error("write crontab", result.stderr, run_as)
+
+
+def _target_user(run_as: str | None) -> str:
+    return run_as or current_user()
+
+
+def list_cron(*, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """List the jobs in a user's crontab as structured records.
+
+    Reads ``crontab -l`` (as ``run_as`` when set) and parses it. A ``#`` comment
+    line directly above a job is attached to that job as its ``comment`` (the
+    convention :func:`add_cron` writes). Environment assignments are returned
+    separately. A user with no crontab yet is reported as ``exists: false`` with
+    no jobs — not an error.
+
+    Returns ``{user, run_as, exists, jobs: [{index, schedule, command, comment,
+    special, raw}], env: [{name, value}], count}``. Raises ToolNotFoundError if
+    ``crontab`` is not installed, CommandError on a real read failure.
+    """
+    if not _crontab_available():
+        raise ToolNotFoundError("crontab not installed or not in PATH")
+
+    raw_lines, exists = _read_crontab(run_as, become_method)
+    jobs: list[dict] = []
+    env: list[dict] = []
+    pending_comment: str | None = None
+    index = 0
+    for line in raw_lines:
+        rec = _parse_line(line)
+        kind = rec["kind"]
+        if kind == "comment":
+            pending_comment = rec["text"]
+        elif kind in ("job", "special"):
+            jobs.append(
+                {
+                    "index": index,
+                    "schedule": rec["schedule"],
+                    "command": rec["command"],
+                    "comment": pending_comment,
+                    "special": kind == "special",
+                    "raw": rec["raw"],
+                }
+            )
+            index += 1
+            pending_comment = None
+        elif kind == "env":
+            env.append({"name": rec["name"], "value": rec["value"]})
+            pending_comment = None
+        else:  # blank / unknown — drop any dangling comment association
+            pending_comment = None
+
+    return {
+        "user": _target_user(run_as),
+        "run_as": run_as or "",
+        "exists": exists,
+        "jobs": jobs,
+        "env": env,
+        "count": len(jobs),
+    }
+
+
+def add_cron(
+    schedule: str,
+    command: str,
+    *,
+    comment: str | None = None,
+    run_as: str | None = None,
+    become_method: str = "sudo",
+    allow_duplicate: bool = False,
+) -> dict:
+    """Add a job (``schedule command``) to a user's crontab.
+
+    ``schedule`` is validated (a 5-field spec or an ``@nickname``); ``command`` is
+    written verbatim (cron runs it via ``/bin/sh``). When ``comment`` is given it
+    is written as a ``# comment`` line directly above the job, so
+    :func:`list_cron` reads it back as the job's ``comment``. Unless
+    ``allow_duplicate`` is set, an identical ``schedule command`` line already
+    present is left as-is (idempotent) and reported with ``added: false``.
+
+    Returns ``{user, run_as, schedule, command, comment, added, count}``. Raises
+    ToolNotFoundError if ``crontab`` is absent, ValueError on bad input,
+    CommandError on a read/write failure.
+    """
+    if not _crontab_available():
+        raise ToolNotFoundError("crontab not installed or not in PATH")
+
+    schedule = validate_schedule(schedule)
+    command = _reject_newline(command.strip(), "command")
+    if not command:
+        raise ValueError("empty command")
+    if comment is not None:
+        comment = _reject_newline(comment.strip(), "comment") or None
+
+    lines, _ = _read_crontab(run_as, become_method)
+    new_line = f"{schedule} {command}"
+
+    if not allow_duplicate and any(line.strip() == new_line for line in lines):
+        listing = list_cron(run_as=run_as, become_method=become_method)
+        return {
+            "user": _target_user(run_as),
+            "run_as": run_as or "",
+            "schedule": schedule,
+            "command": command,
+            "comment": comment,
+            "added": False,
+            "count": listing["count"],
+        }
+
+    if lines and lines[-1].strip() != "":
+        # keep a clean separation; harmless if a blank already trails
+        pass
+    if comment:
+        lines.append(f"# {comment}")
+    lines.append(new_line)
+    _write_crontab(lines, run_as, become_method)
+
+    listing = list_cron(run_as=run_as, become_method=become_method)
+    return {
+        "user": _target_user(run_as),
+        "run_as": run_as or "",
+        "schedule": schedule,
+        "command": command,
+        "comment": comment,
+        "added": True,
+        "count": listing["count"],
+    }
+
+
+def remove_cron(
+    *,
+    match: str | None = None,
+    index: int | None = None,
+    run_as: str | None = None,
+    become_method: str = "sudo",
+) -> dict:
+    """Remove job(s) from a user's crontab.
+
+    Exactly one selector must be given:
+
+    - ``index`` — remove the job at that 0-based position among the crontab's
+      jobs (the ``index`` reported by :func:`list_cron`); a ``# comment`` line
+      directly above it is removed too.
+    - ``match`` — remove every job whose command contains ``match`` as a
+      substring, or whose full ``schedule command`` line equals it; each removed
+      job's preceding ``# comment`` line is removed too.
+
+    Removing nothing is not an error (``removed: []``); the crontab is only
+    rewritten when something was actually removed. Returns ``{user, run_as,
+    removed: [{schedule, command}], count}`` (``count`` = jobs remaining). Raises
+    ToolNotFoundError if ``crontab`` is absent, ValueError on a bad selector,
+    CommandError on a read/write failure.
+    """
+    if not _crontab_available():
+        raise ToolNotFoundError("crontab not installed or not in PATH")
+    if (index is None) == (match is None):
+        raise ValueError("give exactly one of index or match")
+
+    lines, exists = _read_crontab(run_as, become_method)
+
+    # Walk the raw lines, tagging each job with its 0-based job index and the raw
+    # line-number of a comment directly above it, so we can drop both together.
+    job_index = 0
+    drop_lines: set[int] = set()
+    removed: list[dict] = []
+    prev_comment_lineno: int | None = None
+    for lineno, line in enumerate(lines):
+        rec = _parse_line(line)
+        kind = rec["kind"]
+        if kind == "comment":
+            prev_comment_lineno = lineno
+            continue
+        if kind in ("job", "special"):
+            if index is not None:
+                selected = index == job_index
+            else:
+                assert match is not None  # guaranteed by the XOR selector check above
+                selected = match in rec["command"] or line.strip() == match.strip()
+            if selected:
+                drop_lines.add(lineno)
+                if prev_comment_lineno is not None:
+                    drop_lines.add(prev_comment_lineno)
+                removed.append({"schedule": rec["schedule"], "command": rec["command"]})
+            job_index += 1
+        prev_comment_lineno = None
+
+    if index is not None and not removed:
+        raise ValueError(f"no job at index {index} (crontab has {job_index} job(s))")
+
+    if removed:
+        kept = [line for lineno, line in enumerate(lines) if lineno not in drop_lines]
+        _write_crontab(kept, run_as, become_method)
+
+    listing = list_cron(run_as=run_as, become_method=become_method) if exists else {"count": 0}
+    return {
+        "user": _target_user(run_as),
+        "run_as": run_as or "",
+        "removed": removed,
+        "count": listing["count"],
+    }
+
+
+def clear_cron(*, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """Remove a user's entire crontab (``crontab -r``).
+
+    A no-op (reported ``existed: false``) when the user has no crontab. Returns
+    ``{user, run_as, cleared, existed}``. Raises ToolNotFoundError if ``crontab``
+    is absent, CommandError on a real removal failure.
+    """
+    if not _crontab_available():
+        raise ToolNotFoundError("crontab not installed or not in PATH")
+
+    _, exists = _read_crontab(run_as, become_method)
+    if not exists:
+        return {"user": _target_user(run_as), "run_as": run_as or "", "cleared": False, "existed": False}
+
+    result = subprocess.run(build_become(["crontab", "-r"], run_as, become_method), capture_output=True, text=True)
+    if result.returncode != 0:
+        check_become_error("clear crontab", result.stderr, run_as)
+    return {"user": _target_user(run_as), "run_as": run_as or "", "cleared": True, "existed": True}

runspec_linux_core-0.6.0/tests/test_containers_runas.py

@@ -0,0 +1,68 @@
+"""The run_as / become_method escalation on the Docker container helpers.
+
+The subprocess layer is stubbed so no real docker runs; the tests assert the
+escalated argv (the ``sudo -n -u`` / ``su`` prefix) and that no escalation
+happens when run_as is unset.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+import pytest
+
+from runspec_linux_core import containers
+
+
+def _stub(monkeypatch: pytest.MonkeyPatch, stdout: str = "", rc: int = 0, stderr: str = "") -> list[list[str]]:
+    calls: list[list[str]] = []
+
+    def fake_run(argv, capture_output=None, text=None):  # noqa: A002
+        calls.append(argv)
+        return subprocess.CompletedProcess(argv, rc, stdout=stdout, stderr=stderr)
+
+    monkeypatch.setattr(containers.subprocess, "run", fake_run)
+    monkeypatch.setattr(containers, "_docker_available", lambda: True)
+    return calls
+
+
+def test_list_containers_no_run_as(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _stub(monkeypatch, stdout='abc\timg\t"/bin/sh"\tnow\tUp\tweb\n')
+    rows = containers.list_containers()
+    assert calls[0][0] == "docker"  # no escalation prefix
+    assert rows[0]["name"] == "web"
+
+
+def test_list_containers_run_as_escalates(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _stub(monkeypatch, stdout="")
+    containers.list_containers(True, run_as="root")
+    assert calls[0][:4] == ["sudo", "-n", "-u", "root"]
+    assert calls[0][4:7] == ["docker", "ps", "--format"]
+    assert "--all" in calls[0]
+
+
+def test_restart_container_run_as_escalates(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _stub(monkeypatch)
+    out = containers.restart_container("web", run_as="deploy")
+    assert calls[0] == ["sudo", "-n", "-u", "deploy", "docker", "restart", "web"]
+    assert out == {"container": "web", "restarted": True, "run_as": "deploy"}
+
+
+def test_container_logs_run_as_su(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _stub(monkeypatch, stdout="log line 1\nlog line 2\n")
+    out = containers.container_logs("web", 10, run_as="svc", become_method="su")
+    assert calls[0] == ["su", "svc", "-c", "docker logs --tail 10 web"]
+    assert out["count"] == 2
+    assert out["run_as"] == "svc"
+
+
+def test_container_logs_run_as_passwordless_hint(monkeypatch: pytest.MonkeyPatch) -> None:
+    _stub(monkeypatch, rc=1, stderr="sudo: a password is required")
+    with pytest.raises(Exception, match="passwordless sudo is not configured for run-as 'svc'"):
+        containers.container_logs("web", run_as="svc")
+
+
+def test_restart_container_run_as_passwordless_hint(monkeypatch: pytest.MonkeyPatch) -> None:
+    _stub(monkeypatch, rc=1, stderr="sudo: a terminal is required")
+    with pytest.raises(Exception, match="passwordless sudo is not configured for run-as 'svc'"):
+        containers.restart_container("web", run_as="svc")

runspec_linux_core-0.6.0/tests/test_cron.py

@@ -0,0 +1,252 @@
+"""Cron helpers: parsing, validation, the read-modify-write, and run_as escalation.
+
+The subprocess layer is stubbed with an in-memory fake crontab so no real
+``crontab`` runs; the tests assert the parsed records, the schedule guards, the
+rewritten table piped to ``crontab -``, and the escalated argv (the
+``sudo -n -u`` / ``su`` prefix) for another user.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+import pytest
+
+from runspec_linux_core import cron
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
+
+
+class FakeCrontab:
+    """A one-user in-memory crontab driving the stubbed ``subprocess.run``.
+
+    Recognises the three crontab invocations by the tokens present in argv (so it
+    works for both the plain ``["crontab", "-l"]`` form and the
+    ``su user -c "crontab -l"`` form): ``-l`` reads, ``-r`` removes, bare ``-``
+    installs the table piped on stdin. Records every argv for escalation asserts.
+    """
+
+    def __init__(self, lines: list[str] | None = None, exists: bool = True) -> None:
+        self.lines = lines or []
+        self.exists = exists
+        self.calls: list[list[str]] = []
+
+    def run(self, argv, capture_output=None, text=None, input=None):  # noqa: A002
+        self.calls.append(argv)
+        joined = " ".join(argv)
+        if "crontab -l" in joined:
+            if not self.exists:
+                return subprocess.CompletedProcess(argv, 1, stdout="", stderr="no crontab for bob")
+            return subprocess.CompletedProcess(argv, 0, stdout="\n".join(self.lines) + ("\n" if self.lines else ""), stderr="")
+        if "crontab -r" in joined:
+            self.lines = []
+            self.exists = False
+            return subprocess.CompletedProcess(argv, 0, stdout="", stderr="")
+        # bare "crontab -" write from stdin
+        self.lines = (input or "").splitlines()
+        self.exists = True
+        return subprocess.CompletedProcess(argv, 0, stdout="", stderr="")
+
+
+def _install(monkeypatch: pytest.MonkeyPatch, fake: FakeCrontab) -> None:
+    monkeypatch.setattr(cron, "_crontab_available", lambda: True)
+    monkeypatch.setattr(cron.subprocess, "run", fake.run)
+    monkeypatch.setattr(cron, "current_user", lambda: "tester")
+
+
+# ── validate_schedule ──────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("good", ["0 3 * * *", "*/5 * * * 1-5", "@reboot", "@Daily", "15 0 1 * *"])
+def test_validate_schedule_ok(good: str) -> None:
+    # returns normalised (nicknames lowercased, whitespace collapsed)
+    assert cron.validate_schedule(good)
+
+
+@pytest.mark.parametrize("bad", ["", "0 3 * *", "0 3 * * * extra", "@nope", "0 3 * * ;rm", "0 3 * * *\n0 0 * * *"])
+def test_validate_schedule_rejects(bad: str) -> None:
+    with pytest.raises(ValueError):
+        cron.validate_schedule(bad)
+
+
+# ── list_cron ──────────────────────────────────────────────────────────────
+
+
+def test_list_cron_parses_jobs_env_and_comments(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(
+        [
+            "SHELL=/bin/bash",
+            "# nightly backup",
+            "0 3 * * * /opt/app/backup.sh",
+            "",
+            "@reboot /opt/app/warmup.sh",
+        ]
+    )
+    _install(monkeypatch, fake)
+    out = cron.list_cron()
+    assert out["exists"] is True
+    assert out["count"] == 2
+    assert out["env"] == [{"name": "SHELL", "value": "/bin/bash"}]
+    first, second = out["jobs"]
+    assert first == {
+        "index": 0,
+        "schedule": "0 3 * * *",
+        "command": "/opt/app/backup.sh",
+        "comment": "nightly backup",
+        "special": False,
+        "raw": "0 3 * * * /opt/app/backup.sh",
+    }
+    assert second["index"] == 1
+    assert second["schedule"] == "@reboot"
+    assert second["special"] is True
+    assert second["comment"] is None
+
+
+def test_list_cron_no_crontab_is_empty_not_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(exists=False)
+    _install(monkeypatch, fake)
+    out = cron.list_cron(run_as="bob")
+    assert out == {"user": "bob", "run_as": "bob", "exists": False, "jobs": [], "env": [], "count": 0}
+
+
+def test_tool_not_found(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(cron, "_crontab_available", lambda: False)
+    with pytest.raises(ToolNotFoundError):
+        cron.list_cron()
+
+
+# ── add_cron ───────────────────────────────────────────────────────────────
+
+
+def test_add_cron_appends_and_writes(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(["0 1 * * * /existing"])
+    _install(monkeypatch, fake)
+    out = cron.add_cron("0 3 * * *", "/opt/app/backup.sh", comment="nightly backup")
+    assert out["added"] is True
+    assert out["count"] == 2
+    assert fake.lines == ["0 1 * * * /existing", "# nightly backup", "0 3 * * * /opt/app/backup.sh"]
+
+
+def test_add_cron_idempotent_duplicate(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(["0 3 * * * /opt/app/backup.sh"])
+    _install(monkeypatch, fake)
+    out = cron.add_cron("0 3 * * *", "/opt/app/backup.sh")
+    assert out["added"] is False
+    assert out["count"] == 1
+    # no write happened (only reads)
+    assert all("crontab -l" in " ".join(c) for c in fake.calls)
+
+
+def test_add_cron_allow_duplicate(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(["0 3 * * * /opt/app/backup.sh"])
+    _install(monkeypatch, fake)
+    out = cron.add_cron("0 3 * * *", "/opt/app/backup.sh", allow_duplicate=True)
+    assert out["added"] is True
+    assert fake.lines.count("0 3 * * * /opt/app/backup.sh") == 2
+
+
+def test_add_cron_rejects_newline_in_command(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab([])
+    _install(monkeypatch, fake)
+    with pytest.raises(ValueError, match="command must not contain a newline"):
+        cron.add_cron("0 3 * * *", "/bin/true\n0 0 * * * /bin/evil")
+
+
+# ── remove_cron ────────────────────────────────────────────────────────────
+
+
+def test_remove_cron_by_match_drops_job_and_comment(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(
+        [
+            "# nightly backup",
+            "0 3 * * * /opt/app/backup.sh",
+            "0 1 * * * /keep.sh",
+        ]
+    )
+    _install(monkeypatch, fake)
+    out = cron.remove_cron(match="backup.sh")
+    assert out["removed"] == [{"schedule": "0 3 * * *", "command": "/opt/app/backup.sh"}]
+    assert out["count"] == 1
+    assert fake.lines == ["0 1 * * * /keep.sh"]
+
+
+def test_remove_cron_by_index(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(["0 1 * * * /a.sh", "0 2 * * * /b.sh"])
+    _install(monkeypatch, fake)
+    out = cron.remove_cron(index=1)
+    assert out["removed"] == [{"schedule": "0 2 * * *", "command": "/b.sh"}]
+    assert fake.lines == ["0 1 * * * /a.sh"]
+
+
+def test_remove_cron_match_nothing_is_noop(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(["0 1 * * * /a.sh"])
+    _install(monkeypatch, fake)
+    out = cron.remove_cron(match="nomatch")
+    assert out["removed"] == []
+    assert out["count"] == 1
+    # nothing written — only reads
+    assert all("crontab -l" in " ".join(c) for c in fake.calls)
+
+
+def test_remove_cron_bad_index_raises(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(["0 1 * * * /a.sh"])
+    _install(monkeypatch, fake)
+    with pytest.raises(ValueError, match="no job at index 5"):
+        cron.remove_cron(index=5)
+
+
+def test_remove_cron_requires_exactly_one_selector(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab([])
+    _install(monkeypatch, fake)
+    with pytest.raises(ValueError, match="exactly one of index or match"):
+        cron.remove_cron()
+    with pytest.raises(ValueError, match="exactly one of index or match"):
+        cron.remove_cron(match="x", index=0)
+
+
+# ── clear_cron ─────────────────────────────────────────────────────────────
+
+
+def test_clear_cron_removes(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(["0 1 * * * /a.sh"])
+    _install(monkeypatch, fake)
+    out = cron.clear_cron()
+    assert out == {"user": "tester", "run_as": "", "cleared": True, "existed": True}
+    assert any("crontab -r" in " ".join(c) for c in fake.calls)
+
+
+def test_clear_cron_noop_when_absent(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(exists=False)
+    _install(monkeypatch, fake)
+    out = cron.clear_cron()
+    assert out == {"user": "tester", "run_as": "", "cleared": False, "existed": False}
+    assert not any("crontab -r" in " ".join(c) for c in fake.calls)
+
+
+# ── run_as escalation ──────────────────────────────────────────────────────
+
+
+def test_list_cron_run_as_escalates_sudo(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab(["0 1 * * * /a.sh"])
+    _install(monkeypatch, fake)
+    cron.list_cron(run_as="deploy")
+    assert fake.calls[0] == ["sudo", "-n", "-u", "deploy", "crontab", "-l"]
+
+
+def test_add_cron_run_as_write_escalates_su(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = FakeCrontab([])
+    _install(monkeypatch, fake)
+    cron.add_cron("@daily", "/x.sh", run_as="svc", become_method="su")
+    # read then write, both under su -c
+    assert fake.calls[0] == ["su", "svc", "-c", "crontab -l"]
+    write_call = next(c for c in fake.calls if c[:3] == ["su", "svc", "-c"] and c[3] == "crontab -")
+    assert write_call == ["su", "svc", "-c", "crontab -"]
+
+
+def test_run_as_passwordless_hint(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_run(argv, capture_output=None, text=None, input=None):  # noqa: A002
+        return subprocess.CompletedProcess(argv, 1, stdout="", stderr="sudo: a password is required")
+
+    monkeypatch.setattr(cron, "_crontab_available", lambda: True)
+    monkeypatch.setattr(cron.subprocess, "run", fake_run)
+    with pytest.raises(CommandError, match="passwordless sudo is not configured for run-as 'svc'"):
+        cron.list_cron(run_as="svc")

runspec_linux_core-0.4.0/runspec_linux_core/containers.py

@@ -1,88 +0,0 @@
-"""Docker container helpers: list, logs, restart."""
-
-import shutil
-import subprocess
-
-from runspec_linux_core.errors import CommandError, ToolNotFoundError
-
-
-def _docker_available() -> bool:
-    return shutil.which("docker") is not None
-
-
-def list_containers(include_all: bool = False) -> list[dict]:
-    """Return Docker containers (running, or all if ``include_all``).
-
-    Raises ToolNotFoundError if docker is not installed, or CommandError if the
-    ``docker ps`` command returns a non-zero exit.
-    """
-    if not _docker_available():
-        raise ToolNotFoundError("docker not installed or not in PATH")
-
-    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:
-        raise CommandError(result.stderr.strip())
-
-    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],
-            }
-        )
-    return rows
-
-
-def container_logs(container: str, lines: int = 50) -> dict:
-    """Return the last ``lines`` log lines for a container.
-
-    Raises ToolNotFoundError if docker is not installed.
-    """
-    if not _docker_available():
-        raise ToolNotFoundError("docker not installed or not in PATH")
-
-    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()
-    return {"container": container, "lines": output_lines, "count": len(output_lines)}
-
-
-def restart_container(container: str) -> dict:
-    """Restart a container. Returns ``{container, restarted: True}`` on success.
-
-    Raises ToolNotFoundError if docker is not installed, or CommandError if the
-    restart returns a non-zero exit (message is the captured stderr).
-    """
-    if not _docker_available():
-        raise ToolNotFoundError("docker not installed or not in PATH")
-
-    result = subprocess.run(
-        ["docker", "restart", container],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0:
-        raise CommandError(result.stderr.strip())
-    return {"container": container, "restarted": True}