diff --git a/.gitea/CODEOWNERS b/.gitea/CODEOWNERS
new file mode 100644
index 0000000..c40bdfb
--- /dev/null
+++ b/.gitea/CODEOWNERS
@@ -0,0 +1 @@
+* @mdaleo404
diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
new file mode 100644
index 0000000..7a750a1
--- /dev/null
+++ b/.gitea/workflows/ci.yml
@@ -0,0 +1,73 @@
+name: CI
+
+on:
+ push:
+ pull_request:
+
+jobs:
+ precommit-and-security:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: "3.13"
+
+ - name: Install pre-commit
+ run: pip install pre-commit
+
+ - name: Run pre-commit hooks
+ run: pre-commit run --all-files --color always
+
+ - name: Install Poetry and export plugin
+ run: |
+ pip install poetry
+ poetry self add poetry-plugin-export
+
+ - name: Install pip-audit
+ run: pip install pip-audit
+
+ - name: Audit dev dependencies (Poetry lockfile)
+ run: |
+ poetry export -f requirements.txt --without-hashes --with dev \
+ | pip-audit -r /dev/stdin
+
+ typecheck:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.13"
+ - run: pip install mypy
+ - run: mypy
+
+ test:
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ python-version: ["3.11", "3.12", "3.13", "3.14"]
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: ${{ matrix.python-version }}
+ - run: pip install -e . pytest
+ - run: pytest tests/unit tests/security
+ - name: Integration tests (best effort)
+ continue-on-error: true
+ run: pytest tests/integration
+
+ package:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+ - run: pip install build
+ - run: python -m build
diff --git a/.gitea/workflows/security-scan.yml b/.gitea/workflows/security-scan.yml
new file mode 100644
index 0000000..8428c2a
--- /dev/null
+++ b/.gitea/workflows/security-scan.yml
@@ -0,0 +1,188 @@
+name: Security Scan
+
+on:
+ schedule:
+ - cron: 27 8 * * *
+ workflow_dispatch:
+
+jobs:
+ security-scan:
+ runs-on: ubuntu-latest
+
+ env:
+ TARGET_DIR: .
+ COSIGN_VERSION: v3.0.5
+ SYFT_VERSION: v1.42.3
+ GRYPE_VERSION: v0.110.0
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Install Cosign (bootstrap)
+ run: |
+ set -euo pipefail
+
+ FILE="cosign-linux-amd64"
+
+ curl -fLO https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/${FILE}
+
+ chmod +x ${FILE}
+ mv ${FILE} /usr/local/bin/cosign
+
+ cosign version
+
+ - name: Install Syft (verified)
+ run: |
+ set -euo pipefail
+
+ VERSION_NO_V="${SYFT_VERSION#v}"
+ FILE="syft_${VERSION_NO_V}_linux_amd64.tar.gz"
+ BASE_URL="https://github.com/anchore/syft/releases/download/${SYFT_VERSION}"
+
+ curl -fLO ${BASE_URL}/${FILE}
+ curl -fLO ${BASE_URL}/syft_${VERSION_NO_V}_checksums.txt
+ curl -fLO ${BASE_URL}/syft_${VERSION_NO_V}_checksums.txt.sig
+ curl -fLO ${BASE_URL}/syft_${VERSION_NO_V}_checksums.txt.pem
+
+ cosign verify-blob \
+ --signature syft_${VERSION_NO_V}_checksums.txt.sig \
+ --certificate syft_${VERSION_NO_V}_checksums.txt.pem \
+ --certificate-identity-regexp "https://github.com/anchore/syft" \
+ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+ syft_${VERSION_NO_V}_checksums.txt
+
+ CHECKSUM_LINE=$(grep " ${FILE}$" syft_${VERSION_NO_V}_checksums.txt)
+ if [ -z "$CHECKSUM_LINE" ]; then
+ echo "Missing checksum entry for ${FILE}"
+ exit 1
+ fi
+
+ echo "$CHECKSUM_LINE" | sha256sum -c -
+
+ tar -xzf ${FILE}
+ mv syft /usr/local/bin/
+
+ syft version
+
+ - name: Install Grype (verified)
+ run: |
+ set -euo pipefail
+
+ VERSION_NO_V="${GRYPE_VERSION#v}"
+ FILE="grype_${VERSION_NO_V}_linux_amd64.tar.gz"
+ BASE_URL="https://github.com/anchore/grype/releases/download/${GRYPE_VERSION}"
+
+ curl -fLO ${BASE_URL}/${FILE}
+ curl -fLO ${BASE_URL}/grype_${VERSION_NO_V}_checksums.txt
+ curl -fLO ${BASE_URL}/grype_${VERSION_NO_V}_checksums.txt.sig
+ curl -fLO ${BASE_URL}/grype_${VERSION_NO_V}_checksums.txt.pem
+
+ cosign verify-blob \
+ --signature grype_${VERSION_NO_V}_checksums.txt.sig \
+ --certificate grype_${VERSION_NO_V}_checksums.txt.pem \
+ --certificate-identity-regexp "https://github.com/anchore/grype" \
+ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+ grype_${VERSION_NO_V}_checksums.txt
+
+ CHECKSUM_LINE=$(grep " ${FILE}$" grype_${VERSION_NO_V}_checksums.txt)
+ if [ -z "$CHECKSUM_LINE" ]; then
+ echo "Missing checksum entry for ${FILE}"
+ exit 1
+ fi
+
+ echo "$CHECKSUM_LINE" | sha256sum -c -
+
+ tar -xzf ${FILE}
+ mv grype /usr/local/bin/
+
+ grype version
+
+ - name: Generate SBOM
+ working-directory: ${{ env.TARGET_DIR }}
+ run: |
+ syft dir:. -o json > sbom.json
+
+ - name: Show SBOM contents
+ working-directory: ${{ env.TARGET_DIR }}
+ run: |
+ echo "Packages discovered by Syft:"
+ jq -r '.artifacts[] | "\(.name)@\(.version) [\(.type)]"' sbom.json | sort
+
+ - name: Run Grype scan (JSON)
+ id: audit
+ continue-on-error: true
+ working-directory: ${{ env.TARGET_DIR }}
+ run: |
+ grype sbom:sbom.json -o json > grype.json
+
+ echo "Vulnerabilities (fixable only):"
+ jq -r '
+ .matches[]
+ | select((.vulnerability.fix.versions | length) > 0)
+ | "\(.artifact.name)@\(.artifact.version) -> \(.vulnerability.id) [\(.vulnerability.severity)] | fixed: \(.vulnerability.fix.versions[0])"
+ ' grype.json
+
+ # Fail only on fixable MEDIUM/HIGH/CRITICAL
+ jq -e '
+ [
+ .matches[]?
+ | select(
+ (
+ .vulnerability.severity == "Medium" or
+ .vulnerability.severity == "High" or
+ .vulnerability.severity == "Critical"
+ )
+ and
+ (
+ (.vulnerability.fix.versions | length) > 0
+ )
+ )
+ ]
+ | length == 0
+ ' grype.json
+
+ - name: Show full Grype table
+ working-directory: ${{ env.TARGET_DIR }}
+ run: |
+ echo "Full Grype report:"
+ grype sbom:sbom.json -o table
+
+ - name: Notify Node-RED on vulnerabilities
+ if: steps.audit.outcome == 'failure'
+ working-directory: ${{ env.TARGET_DIR }}
+ run: |
+ jq '
+ {
+ repo: "mdaleo404/schedls",
+ summary: (
+ "Total: " +
+ (
+ [
+ .matches[]
+ | select((.vulnerability.fix.versions | length) > 0)
+ ] | length | tostring
+ )
+ ),
+ vulnerabilities: [
+ .matches[]
+ | select((.vulnerability.fix.versions | length) > 0)
+ | {
+ library: .artifact.name,
+ cve: .vulnerability.id,
+ severity: .vulnerability.severity,
+ installed: .artifact.version,
+ fixed: (.vulnerability.fix.versions[0]),
+ title: .vulnerability.description,
+ url: .vulnerability.dataSource
+ }
+ ]
+ }
+ ' grype.json \
+ | curl -s -X POST https://nodered.sysmd.uk/vulns-alert \
+ -H "Content-Type: application/json" \
+ --data-binary @-
+
+ - name: Fail workflow if vulnerabilities found
+ if: steps.audit.outcome == 'failure'
+ run: exit 1
diff --git a/.gitignore b/.gitignore
index 36b13f1..69169fd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -173,4 +173,3 @@ cython_debug/
# PyPI configuration file
.pypirc
-
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..230ca77
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,31 @@
+repos:
+ - repo: https://github.com/pre-commit/pre-commit-hooks
+ rev: v6.0.0
+ hooks:
+ - id: trailing-whitespace
+ name: Enforce removal of trailing whitespace
+ - id: end-of-file-fixer
+ name: Enforce end of the file format
+ - id: check-yaml
+ name: Check YAML syntax
+ - id: check-toml
+ name: Check TOML syntax
+ - id: check-merge-conflict
+ name: Check for merge conflict markers
+
+ - repo: https://github.com/astral-sh/ruff-pre-commit
+ rev: v0.16.8
+ hooks:
+ - id: ruff
+ name: Lint with ruff
+ args: ["--fix"]
+ - id: ruff-format
+ name: Format with ruff
+
+ - repo: https://github.com/PyCQA/bandit
+ rev: 1.9.4
+ hooks:
+ - id: bandit
+ name: Security scan with Bandit
+ files: ^src/
+ args: ["-lll", "-iii", "-s", "B603,B604,B607"]
diff --git a/README.md b/README.md
index e9bfba3..363c013 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,137 @@
+[](https://git.sysmd.uk/mdaleo404/schedls/src/branch/main/LICENSE)
+[](https://git.sysmd.uk/mdaleo404/schedls/releases)
+[](https://git.sysmd.uk/mdaleo404/schedls/src/branch/main/.pre-commit-config.yaml)
+
# schedls
+
+
+
\d{2}))?$")
+
+_WEEKDAY_CALENDAR = {
+ "sun": "Sun",
+ "sunday": "Sun",
+ "mon": "Mon",
+ "monday": "Mon",
+ "tue": "Tue",
+ "tuesday": "Tue",
+ "wed": "Wed",
+ "wednesday": "Wed",
+ "thu": "Thu",
+ "thursday": "Thu",
+ "fri": "Fri",
+ "friday": "Fri",
+ "sat": "Sat",
+ "saturday": "Sat",
+}
+
+_CRON_DOW = {
+ "sun": "0",
+ "sunday": "0",
+ "mon": "1",
+ "monday": "1",
+ "tue": "2",
+ "tuesday": "2",
+ "wed": "3",
+ "wednesday": "3",
+ "thu": "4",
+ "thursday": "4",
+ "fri": "5",
+ "friday": "5",
+ "sat": "6",
+ "saturday": "6",
+}
+
+
+def _parse_time(value: str) -> tuple[int, int, int]:
+ match = _TIME_RE.match(value.strip())
+ if not match:
+ raise InvalidScheduleError(
+ f"invalid time of day: {value!r}",
+ hint="Expected HH:MM or HH:MM:SS (24-hour clock).",
+ )
+ hour = int(match.group("h"))
+ minute = int(match.group("m"))
+ second = int(match.group("s") or 0)
+ if hour > 23 or minute > 59 or second > 59:
+ raise InvalidScheduleError(f"invalid time of day: {value!r}")
+ return hour, minute, second
+
+
+def daily_calendar(time: str) -> str:
+ hour, minute, second = _parse_time(time)
+ return f"*-*-* {hour:02d}:{minute:02d}:{second:02d}"
+
+
+def weekdays_calendar(time: str) -> str:
+ hour, minute, second = _parse_time(time)
+ return f"Mon..Fri *-*-* {hour:02d}:{minute:02d}:{second:02d}"
+
+
+def weekly_calendar(day: str, time: str) -> str:
+ dow = _WEEKDAY_CALENDAR.get(day.strip().lower())
+ if dow is None:
+ raise InvalidScheduleError(
+ f"invalid weekday: {day!r}",
+ hint="Use one of: sun, mon, tue, wed, thu, fri, sat.",
+ )
+ hour, minute, second = _parse_time(time)
+ return f"{dow} *-*-* {hour:02d}:{minute:02d}:{second:02d}"
+
+
+def monthly_calendar(day: str, time: str) -> str:
+ try:
+ day_i = int(day)
+ except ValueError:
+ raise InvalidScheduleError(f"invalid day of month: {day!r}") from None
+ if not 1 <= day_i <= 31:
+ raise InvalidScheduleError(f"day of month out of range: {day!r}")
+ hour, minute, second = _parse_time(time)
+ return f"*-*-{day_i:02d} {hour:02d}:{minute:02d}:{second:02d}"
+
+
+def daily_cron(time: str) -> str:
+ hour, minute, _ = _parse_time(time)
+ return f"{minute} {hour} * * *"
+
+
+def weekdays_cron(time: str) -> str:
+ hour, minute, _ = _parse_time(time)
+ return f"{minute} {hour} * * 1-5"
+
+
+def weekly_cron(day: str, time: str) -> str:
+ dow = _CRON_DOW.get(day.strip().lower())
+ if dow is None:
+ raise InvalidScheduleError(
+ f"invalid weekday: {day!r}",
+ hint="Use one of: sun, mon, tue, wed, thu, fri, sat.",
+ )
+ hour, minute, _ = _parse_time(time)
+ return f"{minute} {hour} * * {dow}"
+
+
+def monthly_cron(day: str, time: str) -> str:
+ try:
+ day_i = int(day)
+ except ValueError:
+ raise InvalidScheduleError(f"invalid day of month: {day!r}") from None
+ if not 1 <= day_i <= 31:
+ raise InvalidScheduleError(f"day of month out of range: {day!r}")
+ hour, minute, _ = _parse_time(time)
+ return f"{minute} {hour} {day_i} * *"
diff --git a/src/schedls/describe.py b/src/schedls/describe.py
new file mode 100644
index 0000000..e788664
--- /dev/null
+++ b/src/schedls/describe.py
@@ -0,0 +1,95 @@
+"""Presentation-only human descriptions of schedules.
+
+This module never validates or interprets schedule *meaning* for execution.
+When a form is not recognised with full confidence the native expression is
+shown unchanged. Correctness beats prettiness.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .models import Schedule, ScheduleKind
+
+_WEEKDAY_NAMES = {
+ 0: "Sunday",
+ 1: "Monday",
+ 2: "Tuesday",
+ 3: "Wednesday",
+ 4: "Thursday",
+ 5: "Friday",
+ 6: "Saturday",
+}
+
+_WEEKDAYS_INDEX = {"Mon": 1, "Tue": 2, "Wed": 3, "Thu": 4, "Fri": 5, "Sat": 6, "Sun": 0}
+
+_CAL_DAILY = re.compile(r"^\*-\*-\*\s+(\d{1,2}):(\d{2}):(\d{2})$")
+_CAL_WEEKDAYS = re.compile(r"^Mon\.\.Fri\s+\*-\*-\*\s+(\d{1,2}):(\d{2}):(\d{2})$")
+_CAL_SINGLE_WEEKDAY = re.compile(r"^(Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s+\*-\*-\*\s+(\d{1,2}):(\d{2}):(\d{2})$")
+_CAL_MONTHLY = re.compile(r"^\*-\*\-(\d{1,2})\s+(\d{1,2}):(\d{2}):(\d{2})$")
+
+_CRON_FIELDS = re.compile(r"^\S+\s+\S+\s+\S+\s+\S+\s+\S+$")
+
+
+def _clock(hour: str, minute: str, second: str) -> str:
+ if second in {"00", "0"}:
+ return f"{int(hour):02d}:{int(minute):02d}"
+ return f"{int(hour):02d}:{int(minute):02d}:{int(second):02d}"
+
+
+def describe_calendar(expression: str) -> str | None:
+ expr = expression.strip()
+ match = _CAL_WEEKDAYS.match(expr)
+ if match:
+ return f"weekdays at {_clock(*match.groups())}"
+ match = _CAL_SINGLE_WEEKDAY.match(expr)
+ if match:
+ return f"{_WEEKDAY_NAMES[_WEEKDAYS_INDEX[match.group(1)]]} at {_clock(*match.groups()[1:])}"
+ match = _CAL_MONTHLY.match(expr)
+ if match:
+ day, hour, minute, second = match.groups()
+ return f"monthly on day {int(day)} at {_clock(hour, minute, second)}"
+ match = _CAL_DAILY.match(expr)
+ if match:
+ return f"daily at {_clock(*match.groups())}"
+ if expr == "daily":
+ return "daily"
+ return None
+
+
+def describe_cron(expression: str) -> str | None:
+ expr = expression.strip()
+ if not _CRON_FIELDS.match(expr):
+ return None
+ minute, hour, dom, month, dow = expr.split()
+ try:
+ minute_i = int(minute)
+ hour_i = int(hour)
+ except ValueError:
+ return None
+ if not (0 <= minute_i <= 59 and 0 <= hour_i <= 23):
+ return None
+ clock = f"{hour_i:02d}:{minute_i:02d}"
+ if dom == "*" and month == "*":
+ if dow == "*":
+ return f"daily at {clock}"
+ if dow == "1-5":
+ return f"weekdays at {clock}"
+ if dow.isdigit() and 0 <= int(dow) <= 6:
+ return f"{_WEEKDAY_NAMES[int(dow)]} at {clock}"
+ if dom.isdigit() and month == "*" and dow == "*":
+ return f"monthly on day {int(dom)} at {clock}"
+ return None
+
+
+def describe_schedule(schedule: Schedule) -> str:
+ if schedule.kind is ScheduleKind.CALENDAR:
+ expression = schedule.expression
+ described = describe_calendar(expression)
+ if described and len(schedule.all_expressions()) == 1:
+ return described
+ if len(schedule.all_expressions()) > 1:
+ return " + ".join(schedule.all_expressions())
+ return expression or "—"
+ described = describe_cron(schedule.expression)
+ return described or schedule.expression or "—"
diff --git a/src/schedls/errors.py b/src/schedls/errors.py
new file mode 100644
index 0000000..fe88632
--- /dev/null
+++ b/src/schedls/errors.py
@@ -0,0 +1,77 @@
+"""Exception hierarchy and stable exit codes for schedls.
+
+Exit codes are part of the public interface and must remain stable:
+
+* ``0`` success
+* ``1`` operational failure
+* ``2`` invalid command-line input or invalid schedule
+* ``3`` safety refusal / conflict
+"""
+
+from __future__ import annotations
+
+EXIT_SUCCESS = 0
+EXIT_FAILURE = 1
+EXIT_USAGE = 2
+EXIT_REFUSED = 3
+
+
+class SchedlsError(Exception):
+ """Base class for all expected schedls failures."""
+
+ exit_code = EXIT_FAILURE
+
+ def __init__(self, message: str, *, hint: str | None = None) -> None:
+ super().__init__(message)
+ self.message = message
+ self.hint = hint
+
+ def render(self) -> str:
+ text = f"Error: {self.message}"
+ if self.hint:
+ text = f"{text}\n\n{self.hint}"
+ return text
+
+
+class UsageError(SchedlsError):
+ """The caller supplied invalid input."""
+
+ exit_code = EXIT_USAGE
+
+
+class InvalidNameError(UsageError):
+ """A schedule name does not match the restricted grammar."""
+
+
+class InvalidScheduleError(UsageError):
+ """A schedule expression could not be validated."""
+
+
+class NotFoundError(SchedlsError):
+ """The requested schedule does not exist."""
+
+
+class OperationalError(SchedlsError):
+ """A helper command or filesystem operation failed."""
+
+
+class DependencyMissingError(OperationalError):
+ """A required native helper executable is unavailable."""
+
+
+class CommandTimeoutError(OperationalError):
+ """A helper command exceeded its allowed execution time."""
+
+
+class SafetyRefusalError(SchedlsError):
+ """schedls declined to perform a risky operation."""
+
+ exit_code = EXIT_REFUSED
+
+
+class ConflictError(SafetyRefusalError):
+ """A destination already exists or an unmanaged object was targeted."""
+
+
+class ConfirmationRequiredError(SafetyRefusalError):
+ """Confirmation was required but cannot be obtained non-interactively."""
diff --git a/src/schedls/interact.py b/src/schedls/interact.py
new file mode 100644
index 0000000..cd3c3e7
--- /dev/null
+++ b/src/schedls/interact.py
@@ -0,0 +1,36 @@
+"""Interactive confirmation handling."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+
+from .errors import ConfirmationRequiredError
+from .output import Output
+
+
+@dataclass
+class Interaction:
+ output: Output
+ assume_yes: bool = False
+
+ def confirm(self, prompt: str, *, default: bool = False) -> bool:
+ if self.assume_yes:
+ return True
+ self.output.stdout.flush()
+ if not sys.stdin.isatty():
+ raise ConfirmationRequiredError(
+ "confirmation required but stdin is not interactive.",
+ hint="Re-run with --yes after reviewing the command.",
+ )
+ suffix = "[Y/n]" if default else "[y/N]"
+ try:
+ answer = input(f"{prompt} {suffix} ").strip().lower()
+ except EOFError:
+ raise ConfirmationRequiredError(
+ "confirmation required but no input was available.",
+ hint="Re-run with --yes after reviewing the command.",
+ ) from None
+ if not answer:
+ return default
+ return answer in {"y", "yes"}
diff --git a/src/schedls/models.py b/src/schedls/models.py
new file mode 100644
index 0000000..5bbe234
--- /dev/null
+++ b/src/schedls/models.py
@@ -0,0 +1,148 @@
+"""Common data model shared by every backend.
+
+The common model describes shared concepts but never erases backend-specific
+facts: those live in typed nested structures attached to each job.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+
+
+class Backend(StrEnum):
+ SYSTEMD = "systemd"
+ CRON = "cron"
+
+
+class Scope(StrEnum):
+ USER = "user"
+ SYSTEM = "system"
+
+
+class ScheduleKind(StrEnum):
+ CALENDAR = "calendar"
+ CRON = "cron"
+
+
+@dataclass(frozen=True)
+class Schedule:
+ """A schedule expressed in a backend's native syntax."""
+
+ kind: ScheduleKind
+ expression: str
+ expressions: tuple[str, ...] = ()
+
+ def all_expressions(self) -> tuple[str, ...]:
+ if self.expressions:
+ return self.expressions
+ return (self.expression,)
+
+
+@dataclass(frozen=True)
+class Command:
+ """An execution request.
+
+ ``argv`` is always the authoritative form. ``shell`` requests that the
+ command be executed through ``/bin/sh -c`` using ``raw``.
+ """
+
+ argv: tuple[str, ...] = ()
+ shell: bool = False
+ raw: str | None = None
+
+ def display(self) -> str:
+ if self.shell and self.raw is not None:
+ return self.raw
+ if not self.argv and self.raw:
+ return self.raw
+ return " ".join(self.argv)
+
+ def is_empty(self) -> bool:
+ return not self.argv and not self.raw
+
+
+@dataclass(frozen=True)
+class JobSource:
+ """Where a discovered job came from."""
+
+ detail: str
+ path: str | None = None
+ line: int | None = None
+
+
+@dataclass(frozen=True)
+class SystemdDetails:
+ timer_unit: str | None = None
+ service_unit: str | None = None
+ timer_path: str | None = None
+ service_path: str | None = None
+ on_calendar: tuple[str, ...] = ()
+ persistent: bool = False
+ jitter: str | None = None
+ accuracy: str | None = None
+ working_directory: str | None = None
+ environment: tuple[tuple[str, str], ...] = ()
+ active_state: str | None = None
+ sub_state: str | None = None
+ unit_file_state: str | None = None
+ result: str | None = None
+ description: str | None = None
+
+
+@dataclass(frozen=True)
+class CronDetails:
+ expression: str | None = None
+ shell: str | None = None
+ mailto: str | None = None
+ raw_line: str | None = None
+ line: int | None = None
+ environment: tuple[tuple[str, str], ...] = ()
+
+
+@dataclass(frozen=True)
+class ScheduledJob:
+ name: str
+ backend: Backend
+ scope: Scope
+ managed: bool
+ enabled: bool | None
+ schedule: Schedule
+ command: Command
+ source: JobSource
+ next_run: datetime | None = None
+ last_run: datetime | None = None
+ last_result: str | None = None
+ warnings: tuple[str, ...] = ()
+ systemd: SystemdDetails | None = None
+ cron: CronDetails | None = None
+
+ def schedule_text(self) -> str:
+ from .describe import describe_schedule
+
+ return describe_schedule(self.schedule)
+
+
+@dataclass(frozen=True)
+class JobSpec:
+ """A request to create or update a scheduled job."""
+
+ name: str
+ backend: Backend
+ scope: Scope
+ command: Command
+ calendar: tuple[str, ...] = ()
+ cron_expression: str | None = None
+ persistent: bool = False
+ jitter: str | None = None
+ accuracy: str | None = None
+ working_directory: str | None = None
+ environment: tuple[tuple[str, str], ...] = field(default_factory=tuple)
+
+ def schedule(self) -> Schedule:
+ if self.backend is Backend.SYSTEMD:
+ expr = self.calendar[0] if self.calendar else ""
+ return Schedule(ScheduleKind.CALENDAR, expr, tuple(self.calendar))
+ expr = self.cron_expression or ""
+ return Schedule(ScheduleKind.CRON, expr)
diff --git a/src/schedls/operations/__init__.py b/src/schedls/operations/__init__.py
new file mode 100644
index 0000000..00c3d45
--- /dev/null
+++ b/src/schedls/operations/__init__.py
@@ -0,0 +1 @@
+"""High-level operations."""
diff --git a/src/schedls/operations/calendar.py b/src/schedls/operations/calendar.py
new file mode 100644
index 0000000..a4395ba
--- /dev/null
+++ b/src/schedls/operations/calendar.py
@@ -0,0 +1,105 @@
+"""``schedls calendar`` — validate and explore systemd calendar syntax."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from ..errors import DependencyMissingError, InvalidScheduleError
+from ..output import Output
+from ..runner import CommandRunner
+from ..security import has_unsafe_control_characters
+from ..timefmt import format_datetime
+
+
+def run_calendar(
+ runner: CommandRunner,
+ output: Output,
+ expression: str,
+ *,
+ next_count: int = 5,
+) -> None:
+ if has_unsafe_control_characters(expression):
+ raise InvalidScheduleError("calendar expressions must not contain control characters")
+ if expression.startswith("-"):
+ raise InvalidScheduleError(f"calendar expression must not start with '-': {expression!r}")
+ if not runner.has("systemd-analyze"):
+ raise DependencyMissingError("systemd-analyze is not available; cannot evaluate calendar expressions.")
+ completed = runner.run(
+ [
+ "systemd-analyze",
+ "calendar",
+ f"--iterations={max(next_count, 1)}",
+ expression,
+ ],
+ check=False,
+ )
+ if completed.returncode != 0:
+ detail = completed.stderr.strip() or completed.stdout.strip()
+ raise InvalidScheduleError(f"invalid calendar expression: {expression!r}", hint=detail or None)
+ original, normalized, occurrences = _parse(completed.stdout)
+ if output.json_mode:
+ output.emit_json(
+ {
+ "schema_version": 1,
+ "expression": expression,
+ "original": original,
+ "normalized": normalized,
+ "next_occurrences": [_iso(dt, utc=output.utc) for dt in occurrences],
+ }
+ )
+ return
+ output.key_values([("Expression", original or expression)])
+ output.line()
+ output.key_values([("Normalized", normalized or expression)])
+ output.line()
+ output.heading("Next occurrences")
+ for occurrence in occurrences:
+ output.line(f" {format_datetime(occurrence, utc=output.utc)}")
+
+
+def _iso(dt: datetime, *, utc: bool) -> str:
+ if utc:
+ dt = dt.astimezone(UTC)
+ return dt.isoformat()
+
+
+def _parse(text: str) -> tuple[str, str, list[datetime]]:
+ original = ""
+ normalized = ""
+ occurrences: list[datetime | None] = []
+ for line in text.splitlines():
+ stripped = line.strip()
+ if stripped.startswith("Original form:"):
+ original = stripped.split(":", 1)[1].strip()
+ elif stripped.startswith("Normalized form:"):
+ normalized = stripped.split(":", 1)[1].strip()
+ elif stripped.startswith("Next elapse:") or stripped.startswith("Iteration #"):
+ occurrences.append(_parse_stamp(stripped.split(":", 1)[1].strip()))
+ elif stripped.startswith("(in UTC):") and occurrences:
+ parsed = _parse_utc(stripped.split(":", 1)[1].strip())
+ if parsed is not None:
+ occurrences[-1] = parsed
+ return original, normalized, [item for item in occurrences if item is not None]
+
+
+def _parse_stamp(stamp: str) -> datetime | None:
+ parts = stamp.split()
+ if len(parts) >= 3:
+ candidate = " ".join(parts[:3])
+ try:
+ parsed = datetime.strptime(candidate, "%a %Y-%m-%d %H:%M:%S")
+ except ValueError:
+ return None
+ return parsed.astimezone()
+ return None
+
+
+def _parse_utc(stamp: str) -> datetime | None:
+ text = stamp.strip()
+ if text.endswith(" UTC"):
+ text = text[: -len(" UTC")]
+ try:
+ parsed = datetime.strptime(text, "%a %Y-%m-%d %H:%M:%S")
+ except ValueError:
+ return None
+ return parsed.replace(tzinfo=UTC)
diff --git a/src/schedls/operations/doctor.py b/src/schedls/operations/doctor.py
new file mode 100644
index 0000000..2deba0f
--- /dev/null
+++ b/src/schedls/operations/doctor.py
@@ -0,0 +1,116 @@
+"""``schedls doctor`` — diagnostic capability report. Never fixes anything."""
+
+from __future__ import annotations
+
+import platform
+from typing import Any
+
+from .. import __version__
+from ..backends.cron import CronBackend
+from ..backends.systemd import SystemdBackend
+from ..models import Scope
+from ..output import Output
+from ..runner import CommandRunner
+
+
+def run_doctor(
+ runner: CommandRunner,
+ output: Output,
+ systemd_backend: SystemdBackend,
+ cron_backend: CronBackend,
+) -> None:
+ systemd = _systemd_report(runner, systemd_backend)
+ cron = _cron_report(runner, cron_backend)
+ usable = systemd["available"] or cron["crontab_available"]
+
+ if output.json_mode:
+ output.emit_json(
+ {
+ "schema_version": 1,
+ "schedls": {"version": __version__, "python": platform.python_version()},
+ "systemd": systemd,
+ "cron": cron,
+ "result": "usable" if usable else "unusable",
+ }
+ )
+ return
+
+ output.heading("schedls")
+ output.key_values([("version", __version__), ("Python", platform.python_version())])
+ output.line()
+ output.heading("systemd")
+ output.key_values(
+ [
+ ("available", _yes_no(systemd["available"])),
+ ("system manager", _reachable(systemd["system_manager"])),
+ ("user manager", _reachable(systemd["user_manager"])),
+ ("systemd-analyze", _yes_no(systemd["analyze"])),
+ ("calendar validation", _yes_no(systemd["calendar_validation"])),
+ ("user lingering", _lingering(systemd["user_lingering"])),
+ ]
+ )
+ output.line()
+ output.heading("cron")
+ output.key_values(
+ [
+ ("crontab", _yes_no(cron["crontab_available"])),
+ ("implementation", cron["implementation"] or "unknown"),
+ ("current user allowed", _yes_no(cron["user_allowed"])),
+ ("syntax validation", _yes_no(cron["validation"])),
+ ]
+ )
+ output.line()
+ output.heading("Result")
+ output.line(f" {'usable' if usable else 'unusable'}")
+
+
+def _systemd_report(runner: CommandRunner, systemd_backend: SystemdBackend) -> dict[str, Any]:
+ analyze = runner.has("systemd-analyze")
+ user_manager = systemd_backend.manager_ok(Scope.USER)
+ system_manager = systemd_backend.manager_ok(Scope.SYSTEM)
+ available = runner.has("systemctl") and (user_manager or system_manager)
+ return {
+ "available": available,
+ "system_manager": system_manager,
+ "user_manager": user_manager,
+ "analyze": analyze,
+ "calendar_validation": analyze and available,
+ "user_lingering": systemd_backend.user_lingering(),
+ }
+
+
+def _cron_report(runner: CommandRunner, cron_backend: CronBackend) -> dict[str, Any]:
+ if not cron_backend.available():
+ return {
+ "crontab_available": False,
+ "implementation": None,
+ "user_allowed": False,
+ "validation": False,
+ }
+ info = cron_backend.capabilities_info()
+ completed = runner.run(["crontab", "-l"], env_policy="identity", check=False)
+ allowed = completed.returncode == 0 or "no crontab" in (completed.stderr + completed.stdout).lower()
+ return {
+ "crontab_available": True,
+ "implementation": info.implementation,
+ "user_allowed": allowed,
+ "validation": info.supports_validation,
+ }
+
+
+def _yes_no(value: bool | None) -> str:
+ if value is None:
+ return "unknown"
+ return "yes" if value else "no"
+
+
+def _reachable(value: bool | None) -> str:
+ if value is None:
+ return "unknown"
+ return "reachable" if value else "unreachable"
+
+
+def _lingering(value: bool | None) -> str:
+ if value is None:
+ return "unknown"
+ return "enabled" if value else "disabled"
diff --git a/src/schedls/operations/inspect.py b/src/schedls/operations/inspect.py
new file mode 100644
index 0000000..2441815
--- /dev/null
+++ b/src/schedls/operations/inspect.py
@@ -0,0 +1,154 @@
+"""Discovery, listing and detail views."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+
+from ..backends.base import SchedulerBackend
+from ..errors import SchedlsError
+from ..models import Backend, ScheduledJob, Scope
+from ..output import Output, jobs_document
+from ..timefmt import format_short
+
+
+def collect(backends: Sequence[SchedulerBackend], scopes: Sequence[Scope]) -> tuple[list[ScheduledJob], list[str]]:
+ jobs: list[ScheduledJob] = []
+ warnings: list[str] = []
+ for backend in backends:
+ if not backend.available():
+ warnings.append(f"{backend.name} backend is unavailable; skipping it.")
+ continue
+ try:
+ jobs.extend(backend.discover(scopes))
+ except SchedlsError as exc:
+ warnings.append(f"{backend.name} discovery failed: {exc.message}")
+ jobs.sort(key=lambda job: (job.name, job.backend.value))
+ if os.geteuid() != 0 and Scope.SYSTEM in scopes:
+ warnings.append(
+ "some system schedules could not be inspected with your current permissions.\n"
+ "Run schedls as root if you intentionally want wider visibility."
+ )
+ return jobs, warnings
+
+
+def job_status(job: ScheduledJob) -> str:
+ if job.enabled is False:
+ return "disabled"
+ if job.backend is Backend.SYSTEMD and job.systemd is not None:
+ sub = job.systemd.sub_state or ""
+ if sub in {"waiting", "running"}:
+ return sub
+ return job.systemd.active_state or "unknown"
+ if job.backend is Backend.CRON:
+ return "active"
+ return "unknown"
+
+
+def filter_jobs(
+ jobs: Sequence[ScheduledJob],
+ *,
+ scope: Scope | None = None,
+ backend: Backend | None = None,
+ managed: bool | None = None,
+ enabled: bool | None = None,
+) -> list[ScheduledJob]:
+ selected = []
+ for job in jobs:
+ if scope is not None and job.scope is not scope:
+ continue
+ if backend is not None and job.backend is not backend:
+ continue
+ if managed is not None and job.managed is not managed:
+ continue
+ if enabled is not None and job.enabled is not enabled:
+ continue
+ selected.append(job)
+ return selected
+
+
+def render_list(output: Output, jobs: Sequence[ScheduledJob], warnings: Sequence[str]) -> None:
+ if output.json_mode:
+ output.emit_json(jobs_document(jobs, warnings))
+ return
+ if not jobs:
+ output.line("No scheduled jobs found.")
+ else:
+ rows = []
+ for job in jobs:
+ next_text = format_short(job.next_run, utc=output.utc) if job.next_run else "—"
+ rows.append(
+ [
+ job.name,
+ job.schedule_text(),
+ next_text,
+ job.backend.value,
+ job.scope.value,
+ job_status(job),
+ ]
+ )
+ output.table(["NAME", "SCHEDULE", "NEXT", "BACKEND", "SCOPE", "STATUS"], rows)
+ for warning in warnings:
+ output.diagnostic(f"Note: {warning}")
+
+
+def render_show(output: Output, job: ScheduledJob) -> None:
+ if output.json_mode:
+ output.emit_json(jobs_document([job]))
+ return
+ output.heading(job.name)
+ output.line()
+ output.key_values([("Status", job_status(job))])
+ output.line()
+ output.key_values([("Backend", _backend_label(job))])
+ output.line()
+ output.key_values([("Managed by schedls", "yes" if job.managed else "no")])
+ output.line()
+ output.key_values([("Schedule", job.schedule_text())])
+ if job.schedule.expressions:
+ for expression in job.schedule.expressions:
+ output.key_values([("OnCalendar", expression)])
+ output.line()
+ output.key_values([("Next", output.job_datetime(job.next_run) or "unknown")])
+ output.line()
+ previous = output.job_datetime(job.last_run) or "unknown"
+ if job.last_result:
+ previous = f"{previous}\nresult: {job.last_result}"
+ output.key_values([("Previous", previous)])
+ output.line()
+ output.key_values([("Command", job.command.display() or "unknown")])
+ if job.systemd is not None:
+ if job.systemd.timer_path:
+ output.line()
+ output.key_values([("Timer", job.systemd.timer_path)])
+ if job.systemd.service_path:
+ output.key_values([("Service", job.systemd.service_path)])
+ extras = []
+ extras.append(("Persistent", "yes" if job.systemd.persistent else "no"))
+ if job.systemd.jitter:
+ extras.append(("Randomized delay", job.systemd.jitter))
+ if job.systemd.accuracy:
+ extras.append(("Accuracy", job.systemd.accuracy))
+ if job.systemd.working_directory:
+ extras.append(("Working directory", job.systemd.working_directory))
+ for key, value in job.systemd.environment:
+ extras.append(("Environment", f"{key}={value}"))
+ if extras:
+ output.line()
+ output.key_values(extras)
+ if job.cron is not None:
+ output.line()
+ output.key_values([("Source", job.source.detail)])
+ if job.cron.shell:
+ output.key_values([("SHELL", job.cron.shell)])
+ if job.cron.mailto:
+ output.key_values([("MAILTO", job.cron.mailto)])
+ for warning in job.warnings:
+ output.line()
+ output.diagnostic(f"Warning: {warning}")
+
+
+def _backend_label(job: ScheduledJob) -> str:
+ if job.backend is Backend.SYSTEMD:
+ return f"systemd {job.scope.value} timer"
+ return "cron"
diff --git a/src/schedls/operations/mutate.py b/src/schedls/operations/mutate.py
new file mode 100644
index 0000000..ca6c945
--- /dev/null
+++ b/src/schedls/operations/mutate.py
@@ -0,0 +1,103 @@
+"""Generic mutation preview, confirmation and application."""
+
+from __future__ import annotations
+
+from ..backends.base import MutationResult, Plan, SchedulerBackend
+from ..interact import Interaction
+from ..output import Output
+
+_TITLES = {
+ "create": "Create scheduled job",
+ "update": "Change scheduled job",
+ "remove": "Remove scheduled job",
+ "enable": "Enable scheduled job",
+ "disable": "Disable scheduled job",
+}
+
+
+def run_plan(
+ backend: SchedulerBackend,
+ plan: Plan,
+ output: Output,
+ interaction: Interaction,
+ *,
+ dry_run: bool = False,
+ show_files: bool = False,
+) -> MutationResult:
+ if not output.json_mode:
+ _preview(output, plan, dry_run=dry_run, show_files=show_files)
+
+ if dry_run:
+ result = MutationResult(changed=False, dry_run=True, warnings=tuple(plan.warnings))
+ if output.json_mode:
+ output.emit_json(_plan_document(plan, result))
+ else:
+ output.line()
+ output.line("No changes made.")
+ return result
+
+ title = _TITLES.get(plan.action, "Apply changes")
+ if not interaction.confirm(f"{title}?"):
+ if output.json_mode:
+ output.emit_json(_plan_document(plan, MutationResult(changed=False)))
+ else:
+ output.line("Aborted. No changes made.")
+ return MutationResult(changed=False)
+
+ result = backend.apply(plan)
+ if output.json_mode:
+ output.emit_json(_plan_document(plan, result))
+ else:
+ for warning in result.warnings:
+ output.warning(warning)
+ for message in result.messages:
+ output.line(message)
+ return result
+
+
+def _plan_document(plan: Plan, result: MutationResult) -> dict[str, object]:
+ return {
+ "schema_version": 1,
+ "action": plan.action,
+ "backend": plan.backend,
+ "changed": result.changed,
+ "dry_run": result.dry_run,
+ "files": list(result.files_written) or plan.display_files(),
+ "commands": [list(command.argv) for command in plan.commands],
+ "warnings": list(result.warnings) or list(plan.warnings),
+ "messages": list(result.messages),
+ }
+
+
+def _preview(output: Output, plan: Plan, *, dry_run: bool, show_files: bool) -> None:
+ title = _TITLES.get(plan.action, "Apply changes")
+ output.heading(f"Would {plan.action}:" if dry_run else f"{title}:")
+
+ if plan.summary:
+ output.line()
+ output.key_values(plan.summary)
+
+ for warning in plan.warnings:
+ output.warning(warning)
+
+ created = [change for change in plan.files if change.content is not None]
+ removed = [change for change in plan.files if change.content is None]
+ if created:
+ output.line()
+ output.line("Would create:" if dry_run else "Will write:")
+ for change in created:
+ output.line(f" {change.path}")
+ if show_files and change.content is not None:
+ for line in change.content.splitlines():
+ output.line(f" {line}")
+ if removed:
+ output.line()
+ output.line("Would remove:" if dry_run else "Will remove:")
+ for change in removed:
+ output.line(f" {change.path}")
+
+ if plan.commands:
+ output.line()
+ output.line("Would run:" if dry_run else "Will run:")
+ for command in plan.commands:
+ output.line(f" {' '.join(command.argv)}")
diff --git a/src/schedls/output.py b/src/schedls/output.py
new file mode 100644
index 0000000..b6e60de
--- /dev/null
+++ b/src/schedls/output.py
@@ -0,0 +1,177 @@
+"""Output abstraction: human tables, key/value views and stable JSON."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from collections.abc import Iterable, Sequence
+from datetime import datetime
+from typing import IO, Any
+
+from .models import ScheduledJob
+from .timefmt import format_datetime, isoformat
+
+SCHEMA_VERSION = 1
+
+_CONTROL_RE = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
+
+
+def sanitize_text(text: str) -> str:
+ """Escape control characters that could manipulate a terminal.
+
+ Newlines and tabs are preserved; every other C0/C1/DEL byte is rendered as
+ a visible ``\\xNN`` sequence.
+ """
+ return _CONTROL_RE.sub(lambda match: f"\\x{ord(match.group(0)):02x}", text)
+
+
+_COLORS = {
+ "reset": "\033[0m",
+ "bold": "\033[1m",
+ "dim": "\033[2m",
+ "red": "\033[31m",
+ "green": "\033[32m",
+ "yellow": "\033[33m",
+}
+
+
+class Output:
+ def __init__(
+ self,
+ *,
+ json_mode: bool = False,
+ color: str = "auto",
+ utc: bool = False,
+ stdout: IO[str] | None = None,
+ stderr: IO[str] | None = None,
+ ) -> None:
+ self.json_mode = json_mode
+ self.color = color
+ self.utc = utc
+ self.stdout = stdout or sys.stdout
+ self.stderr = stderr or sys.stderr
+
+ def use_color(self) -> bool:
+ if self.color == "always":
+ return True
+ if self.color == "never":
+ return False
+ if os.environ.get("NO_COLOR") is not None:
+ return False
+ return self.stdout.isatty()
+
+ def style(self, text: str, *names: str) -> str:
+ if not self.use_color() or not names:
+ return text
+ prefix = "".join(_COLORS[name] for name in names if name in _COLORS)
+ return f"{prefix}{text}{_COLORS['reset']}"
+
+ def line(self, text: str = "") -> None:
+ print(text, file=self.stdout)
+
+ def write(self, text: str) -> None:
+ """Write text verbatim, without adding a trailing newline."""
+ print(text, end="", file=self.stdout)
+
+ def heading(self, text: str) -> None:
+ self.line(self.style(text, "bold"))
+
+ def diagnostic(self, text: str) -> None:
+ print(text, file=self.stderr)
+
+ def warning(self, text: str) -> None:
+ print(self.style(f"Warning: {text}", "yellow"), file=self.stderr)
+
+ def emit_json(self, payload: dict[str, Any]) -> None:
+ self.line(json.dumps(payload, indent=2, ensure_ascii=False, sort_keys=False))
+
+ def table(self, headers: Sequence[str], rows: Iterable[Sequence[str]]) -> None:
+ materialized = [[str(cell) for cell in row] for row in rows]
+ widths = [len(header) for header in headers]
+ for row in materialized:
+ for index, cell in enumerate(row):
+ widths[index] = max(widths[index], len(cell))
+ header_line = " ".join(header.ljust(widths[i]) for i, header in enumerate(headers))
+ self.line(self.style(header_line.rstrip(), "bold"))
+ for row in materialized:
+ self.line(" ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)).rstrip())
+
+ def key_values(self, pairs: Sequence[tuple[str, str]]) -> None:
+ if not pairs:
+ return
+ width = max(len(key) for key, _ in pairs)
+ for key, value in pairs:
+ self.line(f"{key.ljust(width)} {value}".rstrip())
+
+ def job_datetime(self, value: datetime | None) -> str | None:
+ if value is None:
+ return None
+ return format_datetime(value, utc=self.utc)
+
+
+def job_to_dict(job: ScheduledJob) -> dict[str, Any]:
+ schedule: dict[str, Any] = {
+ "kind": job.schedule.kind.value,
+ "expression": job.schedule.expression,
+ }
+ if job.schedule.expressions:
+ schedule["expressions"] = list(job.schedule.expressions)
+
+ data: dict[str, Any] = {
+ "name": job.name,
+ "backend": job.backend.value,
+ "scope": job.scope.value,
+ "managed": job.managed,
+ "enabled": job.enabled,
+ "schedule": schedule,
+ "command": {
+ "argv": list(job.command.argv),
+ "shell": job.command.shell,
+ "raw": job.command.raw,
+ },
+ "source": {
+ "detail": job.source.detail,
+ "path": job.source.path,
+ "line": job.source.line,
+ },
+ "next_run": isoformat(job.next_run) if job.next_run else None,
+ "last_run": isoformat(job.last_run) if job.last_run else None,
+ "last_result": job.last_result,
+ "warnings": list(job.warnings),
+ }
+ if job.systemd is not None:
+ data["systemd"] = {
+ "timer_unit": job.systemd.timer_unit,
+ "service_unit": job.systemd.service_unit,
+ "timer_path": job.systemd.timer_path,
+ "service_path": job.systemd.service_path,
+ "on_calendar": list(job.systemd.on_calendar),
+ "persistent": job.systemd.persistent,
+ "jitter": job.systemd.jitter,
+ "accuracy": job.systemd.accuracy,
+ "working_directory": job.systemd.working_directory,
+ "environment": [list(item) for item in job.systemd.environment],
+ "active_state": job.systemd.active_state,
+ "sub_state": job.systemd.sub_state,
+ "unit_file_state": job.systemd.unit_file_state,
+ "result": job.systemd.result,
+ }
+ if job.cron is not None:
+ data["cron"] = {
+ "expression": job.cron.expression,
+ "shell": job.cron.shell,
+ "mailto": job.cron.mailto,
+ "line": job.cron.line,
+ "environment": [list(item) for item in job.cron.environment],
+ }
+ return data
+
+
+def jobs_document(jobs: Sequence[ScheduledJob], warnings: Sequence[str] = ()) -> dict[str, Any]:
+ return {
+ "schema_version": SCHEMA_VERSION,
+ "jobs": [job_to_dict(job) for job in jobs],
+ "warnings": list(warnings),
+ }
diff --git a/src/schedls/prompt.py b/src/schedls/prompt.py
new file mode 100644
index 0000000..34414dc
--- /dev/null
+++ b/src/schedls/prompt.py
@@ -0,0 +1,201 @@
+"""Interactive input collection for the opt-in guided wizard.
+
+The wizard only gathers input. It never builds a plan, writes a file or runs a
+command: callers turn the collected values into a :class:`JobSpec` and reuse the
+normal preview/confirm/apply path. Prompts are line-based and use the standard
+input stream only; no editor, pager or extra dependency is involved.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+import sys
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from .convenience import (
+ daily_calendar,
+ monthly_calendar,
+ weekly_calendar,
+)
+from .errors import ConfirmationRequiredError, SchedlsError
+from .models import Backend, Command
+from .output import Output
+from .renderers import cron as cron_renderer
+
+InputFn = Callable[[str], str]
+Validator = Callable[[str], object]
+CalendarValidator = Callable[[str], object]
+
+_ENV_NAME_RE = re.compile(r"\A[A-Za-z_][A-Za-z0-9_]*\Z")
+
+
+def _valid_time(value: str) -> str:
+ daily_calendar(value)
+ return value
+
+
+def _valid_day(value: str) -> str:
+ weekly_calendar(value, "00:00")
+ return value
+
+
+def _valid_month_day(value: str) -> str:
+ monthly_calendar(value, "00:00")
+ return value
+
+
+def _valid_cron(value: str) -> str:
+ cron_renderer.validate_expression(value)
+ return value
+
+
+@dataclass
+class Prompter:
+ """Collects values from an interactive terminal.
+
+ ``input_fn`` is resolved at call time so callers and tests can substitute
+ the builtin. ``calendar_validator`` is an optional callable (typically the
+ systemd backend's ``validate_calendar``) used to re-prompt on a bad native
+ ``OnCalendar`` expression.
+ """
+
+ output: Output
+ input_fn: InputFn | None = None
+ calendar_validator: CalendarValidator | None = None
+
+ def require_terminal(self) -> None:
+ if not sys.stdin.isatty():
+ raise ConfirmationRequiredError(
+ "interactive mode requires a terminal.",
+ hint="Re-run without --interactive and pass flags, or run from a terminal.",
+ )
+
+ def text(
+ self,
+ prompt: str,
+ *,
+ default: str | None = None,
+ validator: Validator | None = None,
+ ) -> str:
+ label = f"{prompt} [{default}]" if default else prompt
+ while True:
+ raw = self._read(f"{label}: ").strip()
+ if not raw:
+ if default is not None:
+ raw = default
+ else:
+ self.output.line("A value is required.")
+ continue
+ if validator is None:
+ return raw
+ try:
+ validator(raw)
+ except SchedlsError as exc:
+ hint = f" {exc.hint}" if exc.hint else ""
+ self.output.line(f"{exc.message}{hint}")
+ continue
+ return raw
+
+ def optional_text(self, prompt: str, *, default: str | None = None) -> str | None:
+ label = f"{prompt} [{default}]" if default else f"{prompt} (optional)"
+ raw = self._read(f"{label}: ").strip()
+ if not raw:
+ return default
+ return raw
+
+ def yes_no(self, prompt: str, *, default: bool = False) -> bool:
+ suffix = "[Y/n]" if default else "[y/N]"
+ while True:
+ raw = self._read(f"{prompt} {suffix} ").strip().lower()
+ if not raw:
+ return default
+ if raw in {"y", "yes"}:
+ return True
+ if raw in {"n", "no"}:
+ return False
+ self.output.line("Please answer 'y' or 'n'.")
+
+ def choice(self, prompt: str, options: Sequence[tuple[str, str]], *, default: str | None = None) -> str:
+ self.output.line(prompt)
+ width = len(str(len(options)))
+ for index, (_, label) in enumerate(options, start=1):
+ self.output.line(f" {str(index).rjust(width)}. {label}")
+ values = [value for value, _ in options]
+ hint = f"{prompt} [{default}]" if default else prompt
+ while True:
+ raw = self._read(f"{hint}: ").strip()
+ if not raw and default is not None:
+ return default
+ if raw.isdigit() and 1 <= int(raw) <= len(options):
+ return options[int(raw) - 1][0]
+ if raw in values:
+ return raw
+ self.output.line("Enter a number from the list.")
+
+ def command(self) -> Command:
+ if self.yes_no("Run the command through a shell (/bin/sh -c)?", default=False):
+ return Command(shell=True, raw=self.text("Shell command"))
+ while True:
+ raw = self.text("Command")
+ try:
+ argv = tuple(shlex.split(raw))
+ except ValueError as exc:
+ self.output.line(f"Could not parse the command: {exc}")
+ continue
+ if not argv:
+ self.output.line("A command is required.")
+ continue
+ return Command(argv=argv)
+
+ def environment(self) -> list[str]:
+ self.output.line("Environment variables (KEY=VALUE, blank line to finish):")
+ entries: list[str] = []
+ while True:
+ raw = self._read(" KEY=VALUE: ").strip()
+ if not raw:
+ return entries
+ key, sep, _ = raw.partition("=")
+ if not sep or not _ENV_NAME_RE.match(key):
+ self.output.line("Expected KEY=VALUE with a valid variable name.")
+ continue
+ entries.append(raw)
+
+ def schedule(self, backend: Backend) -> dict[str, object]:
+ options = [
+ ("daily", "Daily at a time"),
+ ("weekdays", "Weekdays (Mon-Fri) at a time"),
+ ("weekly", "Weekly on a day of the week"),
+ ("monthly", "Monthly on a day of the month"),
+ ("custom", "Custom native expression"),
+ ]
+ kind = self.choice("Schedule:", options, default="daily")
+ if kind == "daily":
+ return {"daily": self.text("Time (HH:MM)", validator=_valid_time)}
+ if kind == "weekdays":
+ return {"weekdays": self.text("Time (HH:MM)", validator=_valid_time)}
+ if kind == "weekly":
+ day = self.text("Day of week (sun..sat)", validator=_valid_day)
+ return {"weekly": [day, self.text("Time (HH:MM)", validator=_valid_time)]}
+ if kind == "monthly":
+ day = self.text("Day of month (1-31)", validator=_valid_month_day)
+ return {"monthly": [day, self.text("Time (HH:MM)", validator=_valid_time)]}
+ if backend is Backend.SYSTEMD:
+ return {"calendar": [self.text("OnCalendar expression", validator=self._validate_calendar)]}
+ return {"cron_expr": self.text("Cron expression (five fields)", validator=_valid_cron)}
+
+ def _validate_calendar(self, value: str) -> str:
+ if self.calendar_validator is not None:
+ self.calendar_validator(value)
+ return value
+
+ def _read(self, label: str) -> str:
+ fn = self.input_fn or input
+ try:
+ return fn(label)
+ except EOFError:
+ raise ConfirmationRequiredError(
+ "interactive input ended unexpectedly.",
+ hint="Run without --interactive or provide answers in a terminal.",
+ ) from None
diff --git a/src/schedls/renderers/__init__.py b/src/schedls/renderers/__init__.py
new file mode 100644
index 0000000..c3c9485
--- /dev/null
+++ b/src/schedls/renderers/__init__.py
@@ -0,0 +1 @@
+"""Renderers for native scheduler configuration."""
diff --git a/src/schedls/renderers/cron.py b/src/schedls/renderers/cron.py
new file mode 100644
index 0000000..860f4d2
--- /dev/null
+++ b/src/schedls/renderers/cron.py
@@ -0,0 +1,127 @@
+"""Render cron entries and managed blocks.
+
+Cron executes command text through a shell. schedls keeps an argument vector
+internally and serializes it into a shell-safe command string, then escapes
+``%`` because cron implementations such as Cronie give it special meaning. If
+a safe representation cannot be guaranteed the operation is refused.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+
+from ..errors import InvalidScheduleError, SafetyRefusalError
+from ..models import Command
+from ..security import has_unsafe_control_characters
+
+BLOCK_BEGIN = "# schedls:begin name={name}{extra}"
+BLOCK_END = "# schedls:end name={name}"
+
+_MARKER_RE = re.compile(r"^#\s*schedls:(?Pbegin|end)\s+(?P.*)$")
+_FIELD_RE = re.compile(r"^[0-9A-Za-z*,/\-]+$")
+_NICKNAMES = {
+ "@reboot",
+ "@yearly",
+ "@annually",
+ "@monthly",
+ "@weekly",
+ "@daily",
+ "@midnight",
+ "@hourly",
+}
+_RANGE_RE = re.compile(r"^[0-9]{1,2}-[0-9]{1,2}$")
+
+
+def escape_percent(text: str) -> str:
+ """Escape ``%`` for a cron command field.
+
+ cron implementations such as Cronie translate an unescaped ``%`` into a
+ newline and ``\\%`` into a literal ``%`` before handing the line to the
+ shell. Escaping *every* ``%`` is correct even when it follows a backslash:
+ ``\\`` + ``%`` becomes ``\\\\%``, which cron reduces back to ``\\%``.
+ """
+ return text.replace("%", "\\%")
+
+
+def render_command(command: Command) -> str:
+ if command.shell:
+ raw = command.raw or ""
+ if has_unsafe_control_characters(raw):
+ raise SafetyRefusalError("shell command must not contain NUL or newline")
+ return escape_percent(raw)
+ if not command.argv:
+ raise InvalidScheduleError("no command given")
+ for arg in command.argv:
+ if has_unsafe_control_characters(arg):
+ raise SafetyRefusalError("cron command arguments must not contain NUL or newline")
+ quoted = " ".join(shlex.quote(arg) for arg in command.argv)
+ return escape_percent(quoted)
+
+
+def _validate_field(field: str, *, low: int, high: int, names: bool) -> None:
+ value = field
+ if value == "*":
+ return
+ for part in value.split(","):
+ if not part:
+ raise InvalidScheduleError(f"invalid cron field: {field!r}")
+ step_text, _, step = part.partition("/")
+ if step and (not step.isdigit() or int(step) == 0):
+ raise InvalidScheduleError(f"invalid cron step in field: {field!r}")
+ if step_text == "*":
+ continue
+ if _RANGE_RE.match(step_text):
+ start_str, end_str = step_text.split("-")
+ start, end = int(start_str), int(end_str)
+ if start > end or not (low <= start <= high) or not (low <= end <= high):
+ raise InvalidScheduleError(f"cron range out of bounds: {field!r}")
+ continue
+ if step_text.isdigit():
+ number = int(step_text)
+ if not low <= number <= high:
+ raise InvalidScheduleError(f"cron value out of range: {field!r}")
+ continue
+ if names and step_text.isalpha():
+ continue
+ raise InvalidScheduleError(f"invalid cron field: {field!r}")
+
+
+def validate_expression(expression: str) -> str:
+ expr = expression.strip()
+ if not expr:
+ raise InvalidScheduleError("empty cron expression")
+ if expr.startswith("@"):
+ nickname = expr.split()[0].lower()
+ if nickname not in _NICKNAMES:
+ raise InvalidScheduleError(f"unknown cron nickname: {expr!r}")
+ if expr.lower() != nickname:
+ raise InvalidScheduleError(f"unexpected text after cron nickname: {expr!r}")
+ return nickname
+ fields = expr.split()
+ if len(fields) != 5:
+ raise InvalidScheduleError(
+ f"cron expression must have five fields: {expression!r}",
+ hint="minute hour day-of-month month day-of-week",
+ )
+ minute, hour, dom, month, dow = fields
+ for value, low, high, names in (
+ (minute, 0, 59, False),
+ (hour, 0, 23, False),
+ (dom, 1, 31, False),
+ (month, 1, 12, True),
+ (dow, 0, 7, True),
+ ):
+ if not _FIELD_RE.match(value):
+ raise InvalidScheduleError(f"invalid cron field: {value!r}")
+ _validate_field(value, low=low, high=high, names=names)
+ return " ".join(fields)
+
+
+def render_line(expression: str, command: Command) -> str:
+ return f"{validate_expression(expression)} {render_command(command)}"
+
+
+def render_block(name: str, lines: list[str], *, extra: str = "") -> str:
+ body = [BLOCK_BEGIN.format(name=name, extra=extra), *lines, BLOCK_END.format(name=name)]
+ return "\n".join(body) + "\n"
diff --git a/src/schedls/renderers/systemd.py b/src/schedls/renderers/systemd.py
new file mode 100644
index 0000000..2c4bf2b
--- /dev/null
+++ b/src/schedls/renderers/systemd.py
@@ -0,0 +1,153 @@
+"""Render systemd ``.service`` and ``.timer`` units.
+
+``ExecStart=`` is not ordinary shell syntax. Arguments are serialized with a
+dedicated quoting routine that accounts for whitespace, quotes, backslashes,
+literal ``$`` and ``%`` characters. Every argument is always quoted so an
+argument that begins with a systemd prefix character (``-@:+!``) cannot change
+the meaning of the command line.
+"""
+
+from __future__ import annotations
+
+from ..errors import SafetyRefusalError
+from ..models import Command, JobSpec
+from ..security import MANAGED_COMMENT, has_unsafe_control_characters
+
+
+def quote_systemd_arg(arg: str) -> str:
+ """Quote one argument using systemd unit-file quoting rules."""
+ if has_unsafe_control_characters(arg):
+ raise SafetyRefusalError("command arguments must not contain NUL or newlines")
+ escaped = arg.replace("\\", "\\\\").replace('"', '\\"')
+ escaped = escaped.replace("$", "$$").replace("%", "%%")
+ return f'"{escaped}"'
+
+
+def render_exec_start(command: Command) -> str:
+ if command.shell:
+ raw = command.raw or ""
+ return "ExecStart=/bin/sh -c " + quote_systemd_arg(raw)
+ tokens = [quote_systemd_arg(arg) for arg in command.argv]
+ return "ExecStart=" + " ".join(tokens)
+
+
+def render_service(spec: JobSpec, unit: str) -> str:
+ lines = [
+ MANAGED_COMMENT,
+ f"# Name: {spec.name}",
+ "",
+ "[Unit]",
+ f"Description=schedls job {spec.name}",
+ "",
+ "[Service]",
+ "Type=oneshot",
+ render_exec_start(spec.command),
+ ]
+ if spec.working_directory:
+ lines.append(f"WorkingDirectory={quote_systemd_arg(spec.working_directory)}")
+ for key, value in spec.environment:
+ lines.append(f"Environment={quote_systemd_arg(f'{key}={value}')}")
+ lines.append("")
+ return "\n".join(lines)
+
+
+def render_timer(spec: JobSpec, unit: str, service_unit: str) -> str:
+ lines = [
+ MANAGED_COMMENT,
+ f"# Name: {spec.name}",
+ "",
+ "[Unit]",
+ f"Description=schedls job {spec.name} (timer)",
+ "",
+ "[Timer]",
+ ]
+ for expression in spec.schedule().all_expressions():
+ lines.append(f"OnCalendar={expression}")
+ if spec.persistent:
+ lines.append("Persistent=true")
+ if spec.jitter:
+ lines.append(f"RandomizedDelaySec={spec.jitter}")
+ if spec.accuracy:
+ lines.append(f"AccuracySec={spec.accuracy}")
+ lines.append(f"Unit={service_unit}")
+ lines.extend(
+ [
+ "",
+ "[Install]",
+ "WantedBy=timers.target",
+ "",
+ ]
+ )
+ return "\n".join(lines)
+
+
+def render_units(spec: JobSpec, *, service_unit: str, timer_unit: str) -> dict[str, str]:
+ return {
+ service_unit: render_service(spec, service_unit),
+ timer_unit: render_timer(spec, timer_unit, service_unit),
+ }
+
+
+def unquote_systemd_args(value: str) -> list[str]:
+ """Inverse of :func:`quote_systemd_arg` for a full ExecStart value."""
+ tokens: list[str] = []
+ current: list[str] = []
+ started = False
+ in_quotes = False
+ index = 0
+ length = len(value)
+ while index < length:
+ char = value[index]
+ if char == "\\" and index + 1 < length:
+ current.append(value[index + 1])
+ started = True
+ index += 2
+ continue
+ if char == '"':
+ in_quotes = not in_quotes
+ started = True
+ index += 1
+ continue
+ if char.isspace() and not in_quotes:
+ if started:
+ tokens.append("".join(current))
+ current = []
+ started = False
+ index += 1
+ continue
+ current.append(char)
+ started = True
+ index += 1
+ if started:
+ tokens.append("".join(current))
+ return [_collapse_specials(token) for token in tokens]
+
+
+def _collapse_specials(token: str) -> str:
+ result: list[str] = []
+ index = 0
+ while index < len(token):
+ char = token[index]
+ if char in "$%" and index + 1 < len(token) and token[index + 1] == char:
+ result.append(char)
+ index += 2
+ continue
+ result.append(char)
+ index += 1
+ return "".join(result)
+
+
+def parse_exec_start(value: str, *, shell: str | None = None) -> Command:
+ """Rebuild a :class:`Command` from a native ExecStart value."""
+ stripped = value.strip()
+ if not stripped:
+ return Command()
+ if stripped[0] in "-@:+!":
+ return Command(raw=stripped)
+ prefix = shell or "/bin/sh"
+ shell_prefix = f"{prefix} -c "
+ if stripped.startswith(shell_prefix):
+ remainder = stripped[len(shell_prefix) :]
+ parsed = unquote_systemd_args(remainder)
+ return Command(shell=True, raw=parsed[0] if parsed else "")
+ return Command(argv=tuple(unquote_systemd_args(stripped)))
diff --git a/src/schedls/runner.py b/src/schedls/runner.py
new file mode 100644
index 0000000..84fd9b2
--- /dev/null
+++ b/src/schedls/runner.py
@@ -0,0 +1,194 @@
+"""Centralized, shell-free process execution.
+
+Every helper process launched by schedls goes through :class:`CommandRunner`.
+This is the single place that guarantees ``shell=False``, bounded timeouts,
+controlled environments and debug logging.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+from .errors import CommandTimeoutError, DependencyMissingError, OperationalError, SafetyRefusalError
+from .security import is_acceptable_helper, resolve_helper
+
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+
+_BASE_ENV = {
+ "LC_ALL": "C",
+ "LANG": "C",
+ "SYSTEMD_COLORS": "0",
+ "SYSTEMD_PAGER": "cat",
+ "PAGER": "cat",
+ "GIT_PAGER": "cat",
+}
+
+# Preserved for user-scoped systemd/dbus operations.
+_SESSION_ENV_KEYS = (
+ "DBUS_SESSION_BUS_ADDRESS",
+ "XDG_RUNTIME_DIR",
+ "XDG_SESSION_ID",
+ "XDG_SESSION_TYPE",
+)
+
+# Preserved for crontab, which consults identity variables.
+_IDENTITY_ENV_KEYS = ("HOME", "USER", "LOGNAME", "SHELL", "TERM")
+
+_SECRET_RE = re.compile(r"(?i)(pass|secret|token|key|credential)")
+
+
+@dataclass
+class Completed:
+ argv: tuple[str, ...]
+ returncode: int
+ stdout: str
+ stderr: str
+
+ @property
+ def ok(self) -> bool:
+ return self.returncode == 0
+
+
+@dataclass
+class _RunResult:
+ completed: Completed
+ timed_out: bool = False
+ missing: str | None = None
+ detail: str = ""
+
+
+@dataclass
+class CommandRunner:
+ debug: bool = False
+ timeout: float = DEFAULT_TIMEOUT
+ log: list[_RunResult] = field(default_factory=list)
+
+ def __post_init__(self) -> None:
+ self._resolved: dict[str, str | None] = {}
+
+ def resolve(self, name: str) -> str | None:
+ if os.sep in name:
+ if not os.path.isabs(name) or not is_acceptable_helper(name):
+ return None
+ return name
+ if name not in self._resolved:
+ self._resolved[name] = resolve_helper(name)
+ return self._resolved[name]
+
+ def has(self, name: str) -> bool:
+ return self.resolve(name) is not None
+
+ def run(
+ self,
+ argv: Sequence[str],
+ *,
+ env_policy: str = "minimal",
+ timeout: float | None = None,
+ check: bool = True,
+ input_text: str | None = None,
+ ) -> Completed:
+ if not argv:
+ raise OperationalError("attempted to run an empty command")
+ if os.sep not in argv[0]:
+ resolved = self.resolve(argv[0])
+ if resolved is None:
+ raise DependencyMissingError(f"required command not found: {argv[0]}")
+ executable = resolved
+ else:
+ if not os.path.isabs(argv[0]) or not is_acceptable_helper(argv[0]):
+ raise SafetyRefusalError(f"refusing to run untrusted executable: {argv[0]!r}")
+ executable = argv[0]
+
+ env = self._build_env(env_policy)
+ effective = list(argv)
+ effective[0] = executable
+ self._debug(f"run {' '.join(self._redact(effective))}")
+
+ try:
+ proc = subprocess.run( # noqa: S603 - argv form, shell disabled
+ effective,
+ shell=False,
+ capture_output=True,
+ text=True,
+ env=env,
+ timeout=timeout if timeout is not None else self.timeout,
+ input=input_text,
+ check=False,
+ )
+ except FileNotFoundError as exc:
+ raise DependencyMissingError(f"required command not found: {argv[0]}") from exc
+ except subprocess.TimeoutExpired as exc:
+ raise CommandTimeoutError(
+ f"{argv[0]} did not respond within {timeout if timeout is not None else self.timeout:g} seconds."
+ ) from exc
+
+ completed = Completed(
+ argv=tuple(effective),
+ returncode=proc.returncode,
+ stdout=proc.stdout or "",
+ stderr=proc.stderr or "",
+ )
+ self._debug(f"exit {completed.returncode}")
+ if check and completed.returncode != 0:
+ detail = completed.stderr.strip() or completed.stdout.strip()
+ raise OperationalError(
+ f"command failed ({completed.returncode}): {' '.join(effective)}",
+ hint=detail or None,
+ )
+ return completed
+
+ def try_run(
+ self,
+ argv: Sequence[str],
+ *,
+ env_policy: str = "minimal",
+ timeout: float | None = None,
+ input_text: str | None = None,
+ ) -> Completed | None:
+ """Run a command, returning ``None`` when the helper is unavailable."""
+ if os.sep not in argv[0] and self.resolve(argv[0]) is None:
+ return None
+ try:
+ return self.run(argv, env_policy=env_policy, timeout=timeout, input_text=input_text)
+ except OperationalError:
+ return None
+
+ def _build_env(self, policy: str) -> dict[str, str]:
+ env = dict(_BASE_ENV)
+ env["PATH"] = DEFAULT_PATH
+ if policy == "minimal":
+ return env
+ keys: tuple[str, ...]
+ if policy == "systemd":
+ keys = _SESSION_ENV_KEYS
+ elif policy == "identity":
+ keys = _IDENTITY_ENV_KEYS
+ elif policy == "passthrough":
+ return {**os.environ, **_BASE_ENV}
+ else:
+ raise OperationalError(f"unknown environment policy: {policy}")
+ for key in keys:
+ value = os.environ.get(key)
+ if value is not None:
+ env[key] = value
+ return env
+
+ def _redact(self, argv: Sequence[str]) -> tuple[str, ...]:
+ redacted = []
+ for arg in argv:
+ if "=" in arg and _SECRET_RE.search(arg.split("=", 1)[0]):
+ key, _, _ = arg.partition("=")
+ redacted.append(f"{key}=")
+ else:
+ redacted.append(arg)
+ return tuple(redacted)
+
+ def _debug(self, message: str) -> None:
+ if self.debug:
+ print(f"[schedls] {message}", file=sys.stderr)
diff --git a/src/schedls/security.py b/src/schedls/security.py
new file mode 100644
index 0000000..9abda69
--- /dev/null
+++ b/src/schedls/security.py
@@ -0,0 +1,234 @@
+"""Security primitives: name validation, trusted paths and safe writes."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import shutil
+import stat
+import tempfile
+
+from .errors import InvalidNameError, SafetyRefusalError
+
+NAME_PATTERN = r"[A-Za-z0-9][A-Za-z0-9_.-]{0,63}"
+_NAME_RE = re.compile(rf"\A{NAME_PATTERN}\Z")
+UNIT_PREFIX = "schedls-"
+MANAGED_COMMENT = "# Managed by schedls"
+
+_MANAGED_UNIT_RE = re.compile(rf"\A{UNIT_PREFIX}{NAME_PATTERN}\.(?:service|timer)\Z")
+_SAFE_UNIT_RE = re.compile(r"\A[A-Za-z0-9][A-Za-z0-9:_.@\\-]{0,254}\.(?:service|timer)\Z")
+
+_HELPER_DIR_ALLOWED_MODE_MASK = stat.S_IWGRP | stat.S_IWOTH
+
+
+def validate_name(name: str) -> str:
+ if not _NAME_RE.match(name):
+ raise InvalidNameError(
+ f"invalid schedule name: {name!r}",
+ hint=(
+ "Names must match [A-Za-z0-9][A-Za-z0-9_.-]{0,63}: "
+ "start alphanumeric, then letters, digits, '_', '.' or '-'."
+ ),
+ )
+ return name
+
+
+def unit_name(name: str, suffix: str) -> str:
+ """Build a schedls-owned systemd unit name from a validated schedule name."""
+ return f"{UNIT_PREFIX}{validate_name(name)}.{suffix}"
+
+
+def validate_managed_unit_name(unit: str) -> str:
+ """Accept only unit names schedls itself would create.
+
+ Used before a unit name is turned into a filesystem path so a crafted
+ ``Unit=`` value cannot escape the trusted unit directory.
+ """
+ if not _MANAGED_UNIT_RE.match(unit):
+ raise SafetyRefusalError(f"refusing to use unexpected unit name: {unit!r}")
+ return unit
+
+
+def is_safe_unit_name(unit: str) -> bool:
+ """Whether a discovered unit name is safe to pass to a helper command."""
+ return bool(_SAFE_UNIT_RE.match(unit))
+
+
+def is_managed_unit(unit: str) -> bool:
+ return unit.startswith(UNIT_PREFIX)
+
+
+def validate_absolute_path(path: str, *, what: str) -> str:
+ if not path:
+ raise SafetyRefusalError(f"{what} path is empty")
+ if not os.path.isabs(path):
+ raise SafetyRefusalError(f"{what} path must be absolute: {path!r}")
+ if "\x00" in path:
+ raise SafetyRefusalError(f"{what} path contains a NUL byte")
+ return path
+
+
+def has_unsafe_control_characters(value: str) -> bool:
+ return any(ch in value for ch in ("\x00", "\n", "\r"))
+
+
+def _owner_is_acceptable(uid: int) -> bool:
+ if os.geteuid() == 0:
+ return uid == 0
+ return uid in {0, os.getuid()}
+
+
+def _helper_file_ok(path: str) -> bool:
+ try:
+ st = os.stat(path)
+ except OSError:
+ return False
+ if not stat.S_ISREG(st.st_mode):
+ return False
+ if not _owner_is_acceptable(st.st_uid):
+ return False
+ return not st.st_mode & _HELPER_DIR_ALLOWED_MODE_MASK
+
+
+def _helper_dir_ok(path: str) -> bool:
+ try:
+ st = os.stat(path)
+ except OSError:
+ return False
+ if not stat.S_ISDIR(st.st_mode):
+ return False
+ if not _owner_is_acceptable(st.st_uid):
+ return False
+ return not st.st_mode & _HELPER_DIR_ALLOWED_MODE_MASK
+
+
+def is_acceptable_helper(path: str) -> bool:
+ """Check an executable path is safe to run.
+
+ The file and its containing directory must be owned by root (when running
+ as root) or by root or the current user, and must not be group- or
+ other-writable. Symlinks are resolved so the final target is checked too.
+ """
+ resolved = os.path.abspath(path)
+ for candidate in {resolved, os.path.realpath(resolved)}:
+ if not _helper_file_ok(candidate):
+ return False
+ if not _helper_dir_ok(os.path.dirname(candidate)):
+ return False
+ return True
+
+
+def resolve_helper(name: str) -> str | None:
+ """Resolve a critical helper executable using a controlled lookup.
+
+ Returns an absolute path or ``None``. A resolved helper that is not owned
+ by an acceptable user, or lives in a group-/other-writable directory, is
+ rejected to reduce PATH-hijacking risk.
+ """
+ resolved = shutil.which(name)
+ if not resolved:
+ return None
+ resolved = os.path.abspath(resolved)
+ if not is_acceptable_helper(resolved):
+ return None
+ return resolved
+
+
+def _expected_owner_uid() -> int:
+ return 0 if os.geteuid() == 0 else os.getuid()
+
+
+def check_trusted_directory(path: str, *, expected_uid: int) -> None:
+ """Ensure a destination directory is trusted: real, owned and not writable."""
+ try:
+ st = os.lstat(path)
+ except FileNotFoundError:
+ raise SafetyRefusalError(f"trusted directory does not exist: {path}") from None
+ if stat.S_ISLNK(st.st_mode):
+ raise SafetyRefusalError(f"trusted directory must not be a symlink: {path}")
+ if not stat.S_ISDIR(st.st_mode):
+ raise SafetyRefusalError(f"trusted path is not a directory: {path}")
+ if st.st_uid != expected_uid:
+ raise SafetyRefusalError(f"trusted directory is owned by uid {st.st_uid} (expected {expected_uid}): {path}")
+ if st.st_mode & _HELPER_DIR_ALLOWED_MODE_MASK:
+ raise SafetyRefusalError(f"trusted directory is group- or other-writable: {path}")
+
+
+def check_replaceable(path: str, *, expected_uid: int) -> None:
+ """Reject unexpected symlinks and ownership before overwriting a file."""
+ try:
+ st = os.lstat(path)
+ except FileNotFoundError:
+ return
+ if stat.S_ISLNK(st.st_mode):
+ raise SafetyRefusalError(f"refusing to replace symlink: {path}")
+ if not stat.S_ISREG(st.st_mode):
+ raise SafetyRefusalError(f"refusing to replace non-regular file: {path}")
+ if st.st_uid != expected_uid:
+ raise SafetyRefusalError(f"refusing to replace file owned by uid {st.st_uid} (expected {expected_uid}): {path}")
+
+
+def atomic_write_text(
+ path: str,
+ content: str,
+ *,
+ mode: int = 0o644,
+ expected_uid: int | None = None,
+) -> None:
+ """Write ``content`` to ``path`` atomically.
+
+ The file is created in the same directory, flushed and fsynced before an
+ atomic rename, so a partial write can never be observed at ``path``.
+ """
+ owner = _expected_owner_uid() if expected_uid is None else expected_uid
+ directory = os.path.dirname(path) or "."
+ check_trusted_directory(directory, expected_uid=owner)
+ check_replaceable(path, expected_uid=owner)
+
+ fd, tmp_path = tempfile.mkstemp(prefix=".schedls-", dir=directory)
+ try:
+ os.fchmod(fd, mode)
+ with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
+ handle.write(content)
+ handle.flush()
+ os.fsync(handle.fileno())
+ os.replace(tmp_path, path)
+ os.chmod(path, mode)
+ except BaseException:
+ with contextlib.suppress(FileNotFoundError):
+ os.unlink(tmp_path)
+ raise
+ _fsync_directory(directory)
+
+
+def remove_file(path: str, *, expected_uid: int | None = None) -> bool:
+ """Remove a regular file, refusing symlinks and ownership mismatches."""
+ owner = _expected_owner_uid() if expected_uid is None else expected_uid
+ try:
+ st = os.lstat(path)
+ except FileNotFoundError:
+ return False
+ if stat.S_ISLNK(st.st_mode):
+ raise SafetyRefusalError(f"refusing to remove symlink: {path}")
+ if not stat.S_ISREG(st.st_mode):
+ raise SafetyRefusalError(f"refusing to remove non-regular file: {path}")
+ if st.st_uid != owner:
+ raise SafetyRefusalError(f"refusing to remove file owned by uid {st.st_uid} (expected {owner}): {path}")
+ check_trusted_directory(os.path.dirname(path) or ".", expected_uid=owner)
+ os.unlink(path)
+ _fsync_directory(os.path.dirname(path) or ".")
+ return True
+
+
+def _fsync_directory(directory: str) -> None:
+ try:
+ dir_fd = os.open(directory, os.O_RDONLY | os.O_DIRECTORY)
+ except OSError:
+ return
+ try:
+ os.fsync(dir_fd)
+ except OSError:
+ pass
+ finally:
+ os.close(dir_fd)
diff --git a/src/schedls/timefmt.py b/src/schedls/timefmt.py
new file mode 100644
index 0000000..c595632
--- /dev/null
+++ b/src/schedls/timefmt.py
@@ -0,0 +1,206 @@
+"""Time and duration formatting helpers.
+
+Time is displayed in the host's local timezone by default; exact values always
+include timezone information.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta
+
+_UNITS = (
+ r"us|ms|secs|seconds|second|sec|s|mins|minutes|minute|min|m|"
+ r"hrs|hours|hour|hr|h|days|day|d|weeks|week|w"
+)
+
+_DURATION_RE = re.compile(
+ rf"^(?P-)?(?:\d+(?:\.\d+)?(?:{_UNITS})\s*)+$",
+ re.IGNORECASE,
+)
+
+_DURATION_PART_RE = re.compile(
+ rf"(?P\d+(?:\.\d+)?)\s*(?P{_UNITS})",
+ re.IGNORECASE,
+)
+
+_UNIT_SECONDS = {
+ "us": 1e-6,
+ "ms": 1e-3,
+ "s": 1.0,
+ "sec": 1.0,
+ "secs": 1.0,
+ "second": 1.0,
+ "seconds": 1.0,
+ "m": 60.0,
+ "min": 60.0,
+ "mins": 60.0,
+ "minute": 60.0,
+ "minutes": 60.0,
+ "h": 3600.0,
+ "hr": 3600.0,
+ "hrs": 3600.0,
+ "hour": 3600.0,
+ "hours": 3600.0,
+ "d": 86400.0,
+ "day": 86400.0,
+ "days": 86400.0,
+ "w": 604800.0,
+ "week": 604800.0,
+ "weeks": 604800.0,
+}
+
+_WEEKDAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+_MONTHS = [
+ "Jan",
+ "Feb",
+ "Mar",
+ "Apr",
+ "May",
+ "Jun",
+ "Jul",
+ "Aug",
+ "Sep",
+ "Oct",
+ "Nov",
+ "Dec",
+]
+
+
+def is_valid_duration(value: str) -> bool:
+ return bool(_DURATION_RE.match(value.strip()))
+
+
+def duration_seconds(value: str) -> float:
+ """Parse a systemd-style duration into seconds. Raises ValueError."""
+ text = value.strip()
+ if not text:
+ raise ValueError("empty duration")
+ sign = 1.0
+ if text.startswith("-"):
+ sign = -1.0
+ text = text[1:]
+ total = 0.0
+ matched = False
+ pos = 0
+ for match in _DURATION_PART_RE.finditer(text):
+ if match.start() != pos:
+ raise ValueError(f"invalid duration: {value!r}")
+ pos = match.end()
+ matched = True
+ total += float(match.group("value")) * _UNIT_SECONDS[match.group("unit").lower()]
+ if not matched or pos != len(text):
+ raise ValueError(f"invalid duration: {value!r}")
+ return sign * total
+
+
+def _display(dt: datetime, *, utc: bool) -> datetime:
+ if utc:
+ return dt.astimezone(UTC)
+ return dt.astimezone()
+
+
+def local_zone_name(dt: datetime) -> str:
+ return dt.tzname() or ""
+
+
+def format_datetime(dt: datetime, *, utc: bool = False) -> str:
+ """Full, unambiguous timestamp such as ``Fri 25 Sep 2026 02:00:00 BST``."""
+ dt = _display(dt, utc=utc)
+ weekday = _WEEKDAYS[dt.weekday()]
+ month = _MONTHS[dt.month - 1]
+ stamp = f"{weekday} {dt.day:02d} {month} {dt.year} {dt.hour:02d}:{dt.minute:02d}:{dt.second:02d}"
+ zone = dt.tzname()
+ if zone:
+ stamp = f"{stamp} {zone}"
+ return stamp
+
+
+def format_clock(dt: datetime, *, utc: bool = False) -> str:
+ dt = _display(dt, utc=utc)
+ zone = dt.tzname()
+ clock = f"{dt.hour:02d}:{dt.minute:02d}"
+ return f"{clock} {zone}" if zone else clock
+
+
+def format_short(dt: datetime, *, now: datetime | None = None, utc: bool = False) -> str:
+ """Compact relative-ish timestamp such as ``today 02:00``/``tomorrow 02:00``."""
+ dt = _display(dt, utc=utc)
+ reference = now or datetime.now(dt.tzinfo or None)
+ if utc:
+ reference = reference.astimezone(UTC)
+ day_delta = (dt.date() - reference.date()).days
+ clock = f"{dt.hour:02d}:{dt.minute:02d}"
+ if day_delta == 0:
+ return f"today {clock}"
+ if day_delta == 1:
+ return f"tomorrow {clock}"
+ if day_delta == -1:
+ return f"yesterday {clock}"
+ return f"{_WEEKDAYS[dt.weekday()]} {clock}"
+
+
+def isoformat(dt: datetime) -> str:
+ """ISO 8601 with an explicit timezone offset."""
+ return dt.isoformat()
+
+
+def parse_systemd_timestamp(value: str) -> datetime | None:
+ """Parse the timestamp forms emitted by ``systemctl show``.
+
+ Handles microsecond epoch values, ``usec``/``s`` suffixed values and the
+ ``n/a`` placeholder.
+ """
+ text = value.strip()
+ if not text or text in {"n/a", "0", "infinity"}:
+ return None
+ if text.isdigit():
+ # systemctl prints realtime values in microseconds since the epoch.
+ micros = int(text)
+ if micros == 0:
+ return None
+ return datetime.fromtimestamp(micros / 1_000_000, tz=UTC).astimezone()
+ for suffix, scale in (("us", 1e-6), ("ms", 1e-3), ("s", 1.0)):
+ if text.endswith(suffix):
+ try:
+ seconds = float(text[: -len(suffix)]) * scale
+ except ValueError:
+ return None
+ if seconds <= 0:
+ return None
+ return datetime.fromtimestamp(seconds, tz=UTC).astimezone()
+ try:
+ parsed = datetime.fromisoformat(text)
+ except ValueError:
+ parsed = None
+ if parsed is None:
+ pretty = _parse_pretty(text)
+ return pretty
+ if parsed.tzinfo is None:
+ parsed = parsed.replace(tzinfo=UTC)
+ return parsed.astimezone()
+
+
+def _parse_pretty(text: str) -> datetime | None:
+ """Parse ``Thu 2026-09-24 06:49:28 BST`` (systemd's human form).
+
+ The trailing zone abbreviation is ignored; the naive value is interpreted
+ in the host's local timezone, which is how systemd renders it by default.
+ """
+ parts = text.split()
+ if len(parts) >= 3:
+ candidate = " ".join(parts[:3])
+ try:
+ parsed = datetime.strptime(candidate, "%a %Y-%m-%d %H:%M:%S")
+ except ValueError:
+ return None
+ return parsed.astimezone()
+ return None
+
+
+def now_utc() -> datetime:
+ return datetime.now(UTC)
+
+
+def add_seconds(dt: datetime, seconds: float) -> datetime:
+ return dt + timedelta(seconds=seconds)
diff --git a/src/schedls/unitfile.py b/src/schedls/unitfile.py
new file mode 100644
index 0000000..6655d6a
--- /dev/null
+++ b/src/schedls/unitfile.py
@@ -0,0 +1,63 @@
+"""Minimal, read-only systemd unit-file parser.
+
+Configuration is treated strictly as data. Values are never executed and only
+the keys schedls needs are interpreted.
+"""
+
+from __future__ import annotations
+
+from .security import MANAGED_COMMENT
+
+
+def has_managed_marker(path: str, *, name: str) -> bool:
+ """Whether a unit file carries the schedls ownership marker for ``name``."""
+ try:
+ with open(path, encoding="utf-8", errors="replace") as handle:
+ head = handle.read(4096)
+ except OSError:
+ return False
+ lines = {line.strip() for line in head.splitlines()}
+ return MANAGED_COMMENT in lines and f"# Name: {name}" in lines
+
+
+def read_units(path: str) -> dict[str, list[str]] | None:
+ """Return section -> list of raw ``key=value`` lines, or ``None``."""
+ try:
+ with open(path, encoding="utf-8", errors="replace") as handle:
+ raw_lines = handle.read().splitlines()
+ except OSError:
+ return None
+
+ sections: dict[str, list[str]] = {}
+ current: str | None = None
+ for raw in raw_lines:
+ line = raw.strip()
+ if not line or line.startswith("#") or line.startswith(";"):
+ continue
+ if line.startswith("[") and line.endswith("]"):
+ current = line[1:-1]
+ sections.setdefault(current, [])
+ continue
+ if current is not None:
+ sections[current].append(line)
+ return sections
+
+
+def values(sections: dict[str, list[str]] | None, section: str, key: str) -> list[str]:
+ if not sections:
+ return []
+ result = []
+ prefix = f"{key}="
+ for line in sections.get(section, []):
+ if line.startswith(prefix):
+ result.append(line[len(prefix) :])
+ return result
+
+
+def first(sections: dict[str, list[str]] | None, section: str, key: str) -> str | None:
+ found = values(sections, section, key)
+ return found[-1] if found else None
+
+
+def read_fragment(path: str) -> dict[str, list[str]] | None:
+ return read_units(path)
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..a36bed2
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,73 @@
+"""Shared test fixtures and a controllable fake command runner."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+
+import pytest
+
+from schedls.errors import DependencyMissingError, OperationalError
+from schedls.runner import Completed
+
+
+class FakeRunner:
+ """A duck-typed stand-in for :class:`schedls.runner.CommandRunner`."""
+
+ def __init__(
+ self,
+ handlers: dict[str, Callable] | None = None,
+ available: Iterable[str] = (),
+ ) -> None:
+ self.handlers = handlers or {}
+ self.available = set(available)
+ self.calls: list[tuple[list[str], str, str | None]] = []
+
+ def has(self, name: str) -> bool:
+ return name in self.available
+
+ def resolve(self, name: str) -> str | None:
+ return name if name in self.available else None
+
+ def run(self, argv, *, env_policy="minimal", timeout=None, check=True, input_text=None):
+ args = list(argv)
+ self.calls.append((args, env_policy, input_text))
+ handler = self.handlers.get(args[0])
+ if handler is None:
+ if args[0] not in self.available:
+ raise DependencyMissingError(f"required command not found: {args[0]}")
+ completed = Completed(tuple(args), 0, "", "")
+ else:
+ completed = _coerce(args, handler(args, input_text))
+ if check and completed.returncode != 0:
+ raise OperationalError(
+ f"command failed ({completed.returncode}): {' '.join(args)}",
+ hint=completed.stderr or completed.stdout or None,
+ )
+ return completed
+
+ def try_run(self, argv, *, env_policy="minimal", timeout=None, input_text=None):
+ if argv[0] not in self.available and argv[0] not in self.handlers:
+ return None
+ try:
+ return self.run(argv, env_policy=env_policy, input_text=input_text)
+ except OperationalError:
+ return None
+
+
+def _coerce(args: list[str], result) -> Completed:
+ if isinstance(result, Completed):
+ return result
+ if isinstance(result, str):
+ return Completed(tuple(args), 0, result, "")
+ if isinstance(result, tuple):
+ if len(result) == 3:
+ return Completed(tuple(args), *result)
+ if len(result) == 2:
+ return Completed(tuple(args), 0, result[0], result[1])
+ raise TypeError(f"unsupported fake result: {result!r}")
+ raise TypeError(f"unsupported fake result: {result!r}")
+
+
+@pytest.fixture
+def fake_runner() -> FakeRunner:
+ return FakeRunner()
diff --git a/tests/fixtures/cron/basic.crontab b/tests/fixtures/cron/basic.crontab
new file mode 100644
index 0000000..e476e1e
--- /dev/null
+++ b/tests/fixtures/cron/basic.crontab
@@ -0,0 +1,3 @@
+# schedls:begin name=backup
+0 2 * * * /usr/local/bin/backup /srv/data
+# schedls:end name=backup
diff --git a/tests/fixtures/systemd/basic.service b/tests/fixtures/systemd/basic.service
new file mode 100644
index 0000000..047ef70
--- /dev/null
+++ b/tests/fixtures/systemd/basic.service
@@ -0,0 +1,9 @@
+# Managed by schedls
+# Name: backup
+
+[Unit]
+Description=schedls job backup
+
+[Service]
+Type=oneshot
+ExecStart="/usr/local/bin/backup" "/srv/data"
diff --git a/tests/fixtures/systemd/basic.timer b/tests/fixtures/systemd/basic.timer
new file mode 100644
index 0000000..e3c3d2b
--- /dev/null
+++ b/tests/fixtures/systemd/basic.timer
@@ -0,0 +1,13 @@
+# Managed by schedls
+# Name: backup
+
+[Unit]
+Description=schedls job backup (timer)
+
+[Timer]
+OnCalendar=*-*-* 02:00:00
+Persistent=true
+Unit=schedls-backup.service
+
+[Install]
+WantedBy=timers.target
diff --git a/tests/integration/__init__.py b/tests/integration/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/integration/test_calendar_integration.py b/tests/integration/test_calendar_integration.py
new file mode 100644
index 0000000..0f3af0c
--- /dev/null
+++ b/tests/integration/test_calendar_integration.py
@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import io
+
+import pytest
+
+from schedls.errors import InvalidScheduleError
+from schedls.operations.calendar import run_calendar
+from schedls.output import Output
+from schedls.runner import CommandRunner
+
+pytestmark = pytest.mark.integration
+
+
+def _has_analyze() -> bool:
+ return CommandRunner().has("systemd-analyze")
+
+
+def test_calendar_valid() -> None:
+ if not _has_analyze():
+ pytest.skip("systemd-analyze not available")
+ stream = io.StringIO()
+ output = Output(color="never", stdout=stream)
+ run_calendar(CommandRunner(), output, "Mon..Fri 02:30", next_count=3)
+ text = stream.getvalue()
+ assert "Normalized" in text
+ assert "Mon..Fri *-*-* 02:30:00" in text
+
+
+def test_calendar_invalid() -> None:
+ if not _has_analyze():
+ pytest.skip("systemd-analyze not available")
+ stream = io.StringIO()
+ output = Output(color="never", stdout=stream)
+ with pytest.raises(InvalidScheduleError):
+ run_calendar(CommandRunner(), output, "definitely not a calendar", next_count=1)
diff --git a/tests/integration/test_cron_lifecycle.py b/tests/integration/test_cron_lifecycle.py
new file mode 100644
index 0000000..e31de19
--- /dev/null
+++ b/tests/integration/test_cron_lifecycle.py
@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from schedls.backends.cron import CronBackend
+from schedls.models import Backend, Command, JobSpec, Scope
+from schedls.runner import CommandRunner
+
+pytestmark = pytest.mark.integration
+
+NAME = "schedls-it-cron"
+
+
+def _backend_or_skip() -> CronBackend:
+ backend = CronBackend(CommandRunner())
+ if not backend.available():
+ pytest.skip("crontab not available")
+ if os.environ.get("SCHEDLS_RUN_CRON_TESTS") != "1":
+ pytest.skip("set SCHEDLS_RUN_CRON_TESTS=1 to allow crontab mutation")
+ return backend
+
+
+def _restore(backend: CronBackend, original: str) -> None:
+ backend.runner.run(["crontab", "-"], env_policy="identity", input_text=original, check=False)
+
+
+def test_cron_lifecycle_preserves_content() -> None:
+ backend = _backend_or_skip()
+ original_document = backend.read()
+ original = original_document.text
+ # Add an unrelated line first so we can prove preservation.
+ seeded = original + ("\n" if original and not original.endswith("\n") else "")
+ seeded += "# unrelated comment\n"
+ backend.runner.run(["crontab", "-"], env_policy="identity", input_text=seeded)
+ try:
+ spec = JobSpec(
+ name=NAME,
+ backend=Backend.CRON,
+ scope=Scope.USER,
+ command=Command(argv=("/usr/bin/true", "a b", "50%")),
+ cron_expression="15 2 * * *",
+ )
+ plan = backend.plan_create(spec)
+ result = backend.apply(plan)
+ assert result.changed
+
+ jobs = [job for job in backend.discover([Scope.USER]) if job.name == NAME]
+ assert len(jobs) == 1
+ assert jobs[0].managed is True
+ assert jobs[0].schedule.expression == "15 2 * * *"
+
+ raw = backend.read().text
+ assert "# unrelated comment" in raw
+ assert "a\\%b" not in raw # sanity: percent is escaped, not raw in a bad way
+
+ job = backend.find(NAME)
+ assert job is not None
+ backend.apply(backend.plan_remove(job))
+ assert "# unrelated comment" in backend.read().text
+ assert backend.find(NAME) is None
+ finally:
+ _restore(backend, original)
diff --git a/tests/integration/test_systemd_lifecycle.py b/tests/integration/test_systemd_lifecycle.py
new file mode 100644
index 0000000..cd180cf
--- /dev/null
+++ b/tests/integration/test_systemd_lifecycle.py
@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from schedls.backends.systemd import SystemdBackend
+from schedls.models import Backend, Command, JobSpec, Scope
+from schedls.runner import CommandRunner
+
+pytestmark = pytest.mark.integration
+
+NAME = "schedls-it"
+
+
+def _backend_or_skip() -> SystemdBackend:
+ backend = SystemdBackend(CommandRunner())
+ if not backend.has_systemctl():
+ pytest.skip("systemctl not available")
+ if not backend.manager_ok(Scope.USER):
+ pytest.skip("user systemd manager not reachable")
+ if not backend.has_analyze():
+ pytest.skip("systemd-analyze not available")
+ return backend
+
+
+def _spec(calendar: str) -> JobSpec:
+ return JobSpec(
+ name=NAME,
+ backend=Backend.SYSTEMD,
+ scope=Scope.USER,
+ command=Command(argv=("/bin/true",)),
+ calendar=(calendar,),
+ persistent=True,
+ )
+
+
+def test_systemd_timer_lifecycle() -> None:
+ backend = _backend_or_skip()
+ directory = backend._unit_dir(Scope.USER)
+ timer_path = os.path.join(directory, f"schedls-{NAME}.timer")
+ service_path = os.path.join(directory, f"schedls-{NAME}.service")
+ # Clean any leftover from a previous run.
+ if os.path.exists(timer_path):
+ existing = backend.find(NAME)
+ if existing is not None:
+ backend.apply(backend.plan_remove(existing))
+ try:
+ plan = backend.plan_create(_spec("*-*-* 03:30:00"))
+ result = backend.apply(plan)
+ assert result.changed
+ assert os.path.exists(timer_path)
+ assert os.path.exists(service_path)
+
+ job = backend.find(NAME)
+ assert job is not None
+ assert job.managed is True
+ assert job.schedule.expression == "*-*-* 03:30:00"
+ assert job.command.argv == ("/bin/true",)
+
+ backend.apply(backend.plan_set_enabled(job, False))
+ job = backend.find(NAME)
+ assert job is not None and job.enabled is False
+
+ backend.apply(backend.plan_set_enabled(job, True))
+ job = backend.find(NAME)
+ assert job is not None and job.enabled is True
+
+ backend.apply(backend.plan_update(job, _spec("*-*-* 05:15:00")))
+ job = backend.find(NAME)
+ assert job is not None
+ assert job.schedule.expression == "*-*-* 05:15:00"
+
+ backend.apply(backend.plan_remove(job))
+ assert not os.path.exists(timer_path)
+ assert not os.path.exists(service_path)
+ assert backend.find(NAME) is None
+ finally:
+ leftover = backend.find(NAME)
+ if leftover is not None:
+ backend.apply(backend.plan_remove(leftover))
diff --git a/tests/security/__init__.py b/tests/security/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/security/test_hardening.py b/tests/security/test_hardening.py
new file mode 100644
index 0000000..7330e85
--- /dev/null
+++ b/tests/security/test_hardening.py
@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+SRC = Path(__file__).resolve().parents[2] / "src" / "schedls"
+
+
+def test_no_shell_true_in_production_code() -> None:
+ offenders = []
+ for path in SRC.rglob("*.py"):
+ text = path.read_text()
+ if "subprocess" in text and "shell=True" in text:
+ offenders.append(str(path))
+ assert offenders == []
+
+
+def test_subprocess_confined_to_runner() -> None:
+ offenders = []
+ for path in SRC.rglob("*.py"):
+ if "import subprocess" in path.read_text() and path.name != "runner.py":
+ offenders.append(str(path))
+ assert offenders == []
+
+
+def test_runner_explicitly_disables_shell() -> None:
+ assert "shell=False" in (SRC / "runner.py").read_text()
+
+
+def test_no_os_system_or_popen() -> None:
+ for path in SRC.rglob("*.py"):
+ text = path.read_text()
+ assert "os.system(" not in text, path
+ assert "os.popen(" not in text, path
diff --git a/tests/unit/__init__.py b/tests/unit/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/unit/test_cli.py b/tests/unit/test_cli.py
new file mode 100644
index 0000000..f716224
--- /dev/null
+++ b/tests/unit/test_cli.py
@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import pytest
+
+from schedls.cli import _parse_environment, _spec_for_new, build_parser, main, split_command
+from schedls.errors import InvalidNameError, UsageError
+from schedls.models import Backend, Scope
+
+
+def test_split_command() -> None:
+ head, tail = split_command(["new", "x", "--timer", "--", "/bin/true", "arg"])
+ assert head == ["new", "x", "--timer"]
+ assert tail == ["/bin/true", "arg"]
+ head, tail = split_command(["show", "x"])
+ assert head == ["show", "x"]
+ assert tail == []
+
+
+def test_edit_command_dest_does_not_shadow_subcommand() -> None:
+ args = build_parser().parse_args(["edit", "backup", "--command"])
+ assert args.command == "edit"
+ assert args.replace_command is True
+
+
+def test_spec_for_new_systemd() -> None:
+ args = build_parser().parse_args(["new", "backup", "--timer", "--daily", "02:00", "--persistent"])
+ spec = _spec_for_new(args, ["/usr/local/bin/backup", "/srv/data"])
+ assert spec.backend is Backend.SYSTEMD
+ assert spec.scope is Scope.USER
+ assert spec.calendar == ("*-*-* 02:00:00",)
+ assert spec.command.argv == ("/usr/local/bin/backup", "/srv/data")
+ assert spec.persistent is True
+
+
+def test_spec_for_new_cron() -> None:
+ args = build_parser().parse_args(["new", "cleanup", "--cron", "--cron-expr", "0 4 * * 0"])
+ spec = _spec_for_new(args, ["/usr/local/bin/cleanup"])
+ assert spec.backend is Backend.CRON
+ assert spec.cron_expression == "0 4 * * 0"
+
+
+def test_spec_for_new_system_scope() -> None:
+ args = build_parser().parse_args(["new", "x", "--timer", "--daily", "02:00", "--system"])
+ spec = _spec_for_new(args, ["/bin/true"])
+ assert spec.scope is Scope.SYSTEM
+
+
+def test_spec_for_new_invalid_name() -> None:
+ args = build_parser().parse_args(["new", "../evil", "--timer", "--daily", "02:00"])
+ with pytest.raises(InvalidNameError):
+ _spec_for_new(args, ["/bin/true"])
+
+
+def test_spec_for_new_requires_schedule() -> None:
+ args = build_parser().parse_args(["new", "x", "--timer"])
+ with pytest.raises(UsageError):
+ _spec_for_new(args, ["/bin/true"])
+
+
+def test_new_without_backend_is_usage_error() -> None:
+ assert main(["new", "x", "--daily", "02:00"]) == 2
+
+
+def test_new_without_name_is_usage_error() -> None:
+ assert main(["new", "--timer", "--daily", "02:00"]) == 2
+
+
+def test_interactive_conflicts_with_json() -> None:
+ assert main(["--json", "new", "x", "-i", "--timer", "--daily", "02:00"]) == 2
+
+
+def test_interactive_requires_terminal(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr("sys.stdin", _FakeStdin(isatty=False))
+ assert main(["new", "x", "-i", "--timer", "--daily", "02:00"]) == 3
+
+
+class _FakeStdin:
+ def __init__(self, *, isatty: bool) -> None:
+ self._isatty = isatty
+
+ def isatty(self) -> bool:
+ return self._isatty
+
+
+def test_spec_for_new_shell_mode() -> None:
+ args = build_parser().parse_args(["new", "x", "--timer", "--daily", "02:00", "--shell", "echo hi | cat"])
+ spec = _spec_for_new(args, [])
+ assert spec.command.shell is True
+ assert spec.command.raw == "echo hi | cat"
+
+
+def test_spec_for_new_rejects_systemd_flags_for_cron() -> None:
+ for extra in (["--env", "A=1"], ["--working-directory", "/srv/data"], ["--persistent"], ["--jitter", "5min"]):
+ args = build_parser().parse_args(["new", "x", "--cron", "--daily", "02:00", *extra])
+ with pytest.raises(UsageError):
+ _spec_for_new(args, ["/bin/true"])
+
+
+def test_spec_for_new_rejects_cron_expr_for_timer() -> None:
+ args = build_parser().parse_args(["new", "x", "--timer", "--cron-expr", "0 4 * * *"])
+ with pytest.raises(UsageError):
+ _spec_for_new(args, ["/bin/true"])
+
+
+def test_spec_for_new_rejects_system_scope_for_cron() -> None:
+ args = build_parser().parse_args(["new", "x", "--cron", "--daily", "02:00", "--system"])
+ with pytest.raises(UsageError):
+ _spec_for_new(args, ["/bin/true"])
+
+
+@pytest.mark.parametrize("value", ["0", "-1", "1000001", "abc"])
+def test_logs_lines_must_be_a_bounded_positive_integer(value: str) -> None:
+ with pytest.raises(SystemExit):
+ build_parser().parse_args(["logs", "x", "--lines", value])
+
+
+def test_parse_environment() -> None:
+ assert _parse_environment(["A=1", "B=x=y"]) == (("A", "1"), ("B", "x=y"))
+ with pytest.raises(UsageError):
+ _parse_environment(["NOVALUE"])
+ with pytest.raises(UsageError):
+ _parse_environment(["1BAD=1"])
diff --git a/tests/unit/test_convenience.py b/tests/unit/test_convenience.py
new file mode 100644
index 0000000..fad8f0a
--- /dev/null
+++ b/tests/unit/test_convenience.py
@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import pytest
+
+from schedls import convenience
+from schedls.errors import InvalidScheduleError
+
+
+@pytest.mark.parametrize(
+ ("time", "expected"),
+ [("02:00", "*-*-* 02:00:00"), ("2:05", "*-*-* 02:05:00"), ("23:59:59", "*-*-* 23:59:59")],
+)
+def test_daily_calendar(time: str, expected: str) -> None:
+ assert convenience.daily_calendar(time) == expected
+
+
+def test_weekdays_and_weekly_calendar() -> None:
+ assert convenience.weekdays_calendar("08:30") == "Mon..Fri *-*-* 08:30:00"
+ assert convenience.weekly_calendar("sun", "04:00") == "Sun *-*-* 04:00:00"
+ assert convenience.weekly_calendar("Saturday", "4:00") == "Sat *-*-* 04:00:00"
+ assert convenience.monthly_calendar("1", "06:00") == "*-*-01 06:00:00"
+
+
+def test_cron_variants() -> None:
+ assert convenience.daily_cron("02:00") == "0 2 * * *"
+ assert convenience.weekdays_cron("08:30") == "30 8 * * 1-5"
+ assert convenience.weekly_cron("sun", "04:00") == "0 4 * * 0"
+ assert convenience.monthly_cron("15", "06:00") == "0 6 15 * *"
+
+
+@pytest.mark.parametrize("bad", ["25:00", "02:60", "nope", "2", "02:00:99"])
+def test_invalid_time(bad: str) -> None:
+ with pytest.raises(InvalidScheduleError):
+ convenience.daily_calendar(bad)
+
+
+def test_invalid_weekday_and_day() -> None:
+ with pytest.raises(InvalidScheduleError):
+ convenience.weekly_calendar("funday", "04:00")
+ with pytest.raises(InvalidScheduleError):
+ convenience.monthly_calendar("32", "06:00")
+ with pytest.raises(InvalidScheduleError):
+ convenience.monthly_calendar("x", "06:00")
diff --git a/tests/unit/test_crontab.py b/tests/unit/test_crontab.py
new file mode 100644
index 0000000..8e24aa3
--- /dev/null
+++ b/tests/unit/test_crontab.py
@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import pytest
+
+from schedls.backends.cron import CrontabDocument
+from schedls.errors import ConflictError, SafetyRefusalError
+
+SAMPLE = (
+ "MAILTO=admin@example.net\n"
+ "SHELL=/bin/bash\n"
+ "PATH=/usr/local/bin:/usr/bin\n"
+ "\n"
+ "# personal job\n"
+ "15 7 * * * ~/bin/foo\n"
+ "@daily /usr/local/bin/nightly\n"
+ "\n"
+ "# schedls:begin name=backup\n"
+ "0 2 * * * /usr/local/bin/backup /srv/data\n"
+ "# schedls:end name=backup\n"
+)
+
+
+def test_lossless_round_trip() -> None:
+ document = CrontabDocument(SAMPLE)
+ assert document.render() == SAMPLE
+
+
+def test_managed_block_detected() -> None:
+ document = CrontabDocument(SAMPLE)
+ blocks = document.managed_blocks()
+ assert list(blocks) == ["backup"]
+ assert blocks["backup"].job_lines[0].expression == "0 2 * * *"
+ assert blocks["backup"].job_lines[0].command == "/usr/local/bin/backup /srv/data"
+ assert not document.has_malformed_markers()
+
+
+def test_environment_and_nickname_parsed() -> None:
+ document = CrontabDocument(SAMPLE)
+ kinds = [entry.kind for entry in document.entries]
+ assert kinds.count("env") == 3
+ assert kinds.count("comment") == 1
+ assert kinds.count("managed_begin") == 1
+ assert kinds.count("managed_end") == 1
+ jobs = [entry for entry in document.entries if entry.kind == "job"]
+ assert jobs[0].expression == "15 7 * * *"
+ assert jobs[1].expression == "@daily"
+
+
+def test_with_block_preserves_unrelated_content() -> None:
+ document = CrontabDocument(SAMPLE)
+ updated = document.with_block("report", ["30 6 * * * /usr/local/bin/report"])
+ assert "MAILTO=admin@example.net" in updated
+ assert "15 7 * * * ~/bin/foo" in updated
+ assert "0 2 * * * /usr/local/bin/backup /srv/data" in updated
+ assert "# schedls:begin name=report" in updated
+ reparsed = CrontabDocument(updated)
+ assert set(reparsed.managed_blocks()) == {"backup", "report"}
+
+
+def test_with_block_conflict() -> None:
+ document = CrontabDocument(SAMPLE)
+ with pytest.raises(ConflictError):
+ document.with_block("backup", ["0 3 * * * /bin/true"])
+
+
+def test_without_block_removes_only_block() -> None:
+ document = CrontabDocument(SAMPLE)
+ updated = document.without_block("backup")
+ assert "backup" not in updated
+ assert "MAILTO=admin@example.net" in updated
+ assert "15 7 * * * ~/bin/foo" in updated
+ assert "@daily /usr/local/bin/nightly" in updated
+
+
+def test_without_unknown_block_refused() -> None:
+ document = CrontabDocument(SAMPLE)
+ with pytest.raises(SafetyRefusalError):
+ document.without_block("nope")
+
+
+def test_malformed_marker_blocks_mutation() -> None:
+ document = CrontabDocument("# schedls:begin name=broken\n0 2 * * * /bin/true\n")
+ assert document.has_malformed_markers()
+ with pytest.raises(SafetyRefusalError):
+ document.with_block("new", ["0 3 * * * /bin/true"])
+ with pytest.raises(SafetyRefusalError):
+ document.without_block("broken")
+
+
+def test_empty_crontab() -> None:
+ document = CrontabDocument("")
+ assert document.render() == ""
+ updated = document.with_block("x", ["0 0 * * * /bin/true"])
+ assert updated.endswith("\n")
+ assert "name=x" in updated
diff --git a/tests/unit/test_describe.py b/tests/unit/test_describe.py
new file mode 100644
index 0000000..458b45a
--- /dev/null
+++ b/tests/unit/test_describe.py
@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from schedls.describe import describe_calendar, describe_cron, describe_schedule
+from schedls.models import Schedule, ScheduleKind
+
+
+def test_describe_calendar() -> None:
+ assert describe_calendar("*-*-* 02:00:00") == "daily at 02:00"
+ assert describe_calendar("Mon..Fri *-*-* 08:30:00") == "weekdays at 08:30"
+ assert describe_calendar("Sun *-*-* 04:00:00") == "Sunday at 04:00"
+ assert describe_calendar("*-*-01 06:00:00") == "monthly on day 1 at 06:00"
+ assert describe_calendar("*-*-* *:00:00") is None
+
+
+def test_describe_cron() -> None:
+ assert describe_cron("0 2 * * *") == "daily at 02:00"
+ assert describe_cron("30 8 * * 1-5") == "weekdays at 08:30"
+ assert describe_cron("0 4 * * 0") == "Sunday at 04:00"
+ assert describe_cron("0 6 15 * *") == "monthly on day 15 at 06:00"
+ assert describe_cron("0 4 1,15 * 5") is None
+ assert describe_cron("@daily") is None
+
+
+def test_describe_schedule() -> None:
+ assert describe_schedule(Schedule(ScheduleKind.CALENDAR, "*-*-* 02:00:00")) == "daily at 02:00"
+ assert describe_schedule(Schedule(ScheduleKind.CRON, "@reboot")) == "@reboot"
+ multi = Schedule(ScheduleKind.CALENDAR, "A", ("A", "B"))
+ assert describe_schedule(multi) == "A + B"
diff --git a/tests/unit/test_operations.py b/tests/unit/test_operations.py
new file mode 100644
index 0000000..655e368
--- /dev/null
+++ b/tests/unit/test_operations.py
@@ -0,0 +1,393 @@
+from __future__ import annotations
+
+import io
+import os
+import tempfile
+from dataclasses import replace
+
+import pytest
+
+from schedls.backends.base import CommandPlan, FileChange, MutationResult, Plan
+from schedls.backends.cron import CronBackend
+from schedls.backends.systemd import SystemdBackend
+from schedls.errors import InvalidScheduleError, OperationalError, SafetyRefusalError
+from schedls.interact import Interaction
+from schedls.models import (
+ Backend,
+ Command,
+ JobSource,
+ JobSpec,
+ Schedule,
+ ScheduledJob,
+ ScheduleKind,
+ Scope,
+ SystemdDetails,
+)
+from schedls.operations import doctor as doctor_ops
+from schedls.operations import inspect as inspect_ops
+from schedls.operations import mutate as mutate_ops
+from schedls.output import Output
+
+from ..conftest import FakeRunner
+
+
+def _job(name: str = "backup") -> ScheduledJob:
+ return ScheduledJob(
+ name=name,
+ backend=Backend.SYSTEMD,
+ scope=Scope.USER,
+ managed=True,
+ enabled=True,
+ schedule=Schedule(ScheduleKind.CALENDAR, "*-*-* 02:00:00"),
+ command=Command(argv=("/usr/local/bin/backup",)),
+ source=JobSource("systemd user timer"),
+ )
+
+
+def _output() -> tuple[Output, io.StringIO]:
+ stream = io.StringIO()
+ return Output(color="never", stdout=stream), stream
+
+
+def test_render_list_table() -> None:
+ output, stream = _output()
+ inspect_ops.render_list(output, [_job(), _job("cleanup")], [])
+ text = stream.getvalue()
+ assert "NAME" in text and "SCHEDULE" in text
+ assert "backup" in text and "cleanup" in text
+
+
+def test_render_list_json() -> None:
+ output, stream = _output()
+ output.json_mode = True
+ inspect_ops.render_list(output, [_job()], ["note"])
+ assert '"schema_version": 1' in stream.getvalue()
+
+
+def test_render_show() -> None:
+ output, stream = _output()
+ inspect_ops.render_show(output, _job())
+ text = stream.getvalue()
+ assert "Managed by schedls" in text
+ assert "systemd user timer" in text
+
+
+def test_filter_jobs() -> None:
+ jobs = [_job(), _job("other")]
+ assert inspect_ops.filter_jobs(jobs, managed=True) == jobs
+ assert inspect_ops.filter_jobs(jobs, managed=False) == []
+ assert inspect_ops.filter_jobs(jobs, enabled=False) == []
+ assert len(inspect_ops.filter_jobs(jobs, backend=Backend.SYSTEMD)) == 2
+
+
+def test_collect_reports_unavailable_backend() -> None:
+ backend = SystemdBackend(FakeRunner())
+ jobs, warnings = inspect_ops.collect([backend], [Scope.USER])
+ assert jobs == []
+ assert any("unavailable" in warning for warning in warnings)
+
+
+class _DummyBackend:
+ name = "systemd"
+
+ def __init__(self, result: MutationResult) -> None:
+ self.result = result
+ self.applied = False
+
+ def apply(self, plan: Plan) -> MutationResult:
+ self.applied = True
+ return self.result
+
+
+def test_run_plan_dry_run(tmp_path) -> None:
+ output, stream = _output()
+ plan = Plan(backend="systemd", action="create")
+ plan.files = [FileChange(str(tmp_path / "example.service"), "data")]
+ plan.commands = [CommandPlan(("systemctl", "reload"), "reload")]
+ backend = _DummyBackend(MutationResult(changed=True))
+ result = mutate_ops.run_plan(backend, plan, output, Interaction(output=output), dry_run=True)
+ assert result.dry_run is True
+ assert backend.applied is False
+ assert "No changes made." in stream.getvalue()
+
+
+def test_run_plan_confirms_and_applies() -> None:
+ output, stream = _output()
+ plan = Plan(backend="systemd", action="create")
+ backend = _DummyBackend(MutationResult(changed=True, messages=["done"]))
+ interaction = Interaction(output=output, assume_yes=True)
+ result = mutate_ops.run_plan(backend, plan, output, interaction)
+ assert backend.applied is True
+ assert result.changed is True
+ assert "done" in stream.getvalue()
+
+
+def test_run_plan_json_mode() -> None:
+ output, stream = _output()
+ output.json_mode = True
+ plan = Plan(backend="systemd", action="create")
+ backend = _DummyBackend(MutationResult(changed=True))
+ mutate_ops.run_plan(backend, plan, output, Interaction(output=output, assume_yes=True))
+ assert '"action": "create"' in stream.getvalue()
+
+
+def _doctor_runner() -> FakeRunner:
+ def systemctl(argv, _input):
+ if "is-system-running" in argv:
+ return ("running\n", "")
+ return ("", "")
+
+ def crontab(argv, _input):
+ if "-V" in argv:
+ return ("cronie 1.7.2\n", "")
+ return ("", "")
+
+ return FakeRunner(
+ handlers={
+ "systemctl": systemctl,
+ "crontab": crontab,
+ "loginctl": lambda argv, _input: ("Linger=no\n", ""),
+ },
+ available={"systemctl", "systemd-analyze", "crontab", "loginctl"},
+ )
+
+
+def test_doctor_human() -> None:
+ runner = _doctor_runner()
+ output, stream = _output()
+ doctor_ops.run_doctor(runner, output, SystemdBackend(runner), CronBackend(runner))
+ text = stream.getvalue()
+ assert "Cronie" in text
+ assert "usable" in text
+
+
+def test_doctor_json() -> None:
+ runner = _doctor_runner()
+ output, stream = _output()
+ output.json_mode = True
+ doctor_ops.run_doctor(runner, output, SystemdBackend(runner), CronBackend(runner))
+ assert '"result": "usable"' in stream.getvalue()
+
+
+def test_systemd_backend_discovery_parses_units() -> None:
+ timer = (
+ "# Managed by schedls\n"
+ "# Name: backup\n"
+ "[Unit]\nDescription=foo\n[Timer]\nOnCalendar=*-*-* 02:00:00\nPersistent=true\nUnit=schedls-backup.service\n"
+ )
+ service = '[Service]\nExecStart="/usr/local/bin/backup" "/srv/data"\n'
+
+ with tempfile.TemporaryDirectory() as tmp:
+ timer_path = os.path.join(tmp, "schedls-backup.timer")
+ service_path = os.path.join(tmp, "schedls-backup.service")
+ with open(timer_path, "w") as handle:
+ handle.write(timer)
+ with open(service_path, "w") as handle:
+ handle.write(service)
+
+ def systemctl(argv, _input):
+ if "is-system-running" in argv:
+ return ("running\n", "")
+ if "list-unit-files" in argv or "list-units" in argv:
+ return ("schedls-backup.timer enabled\n", "")
+ if "show" in argv:
+ unit = argv[argv.index("show") + 1]
+ if unit.endswith(".timer"):
+ return (
+ f"Id={unit}\nLoadState=loaded\nFragmentPath={timer_path}\n"
+ "UnitFileState=enabled\nActiveState=active\nSubState=waiting\n"
+ "NextElapseUSecRealtime=1758700800000000\nTriggers=schedls-backup.service\n",
+ "",
+ )
+ return (
+ f"Id={unit}\nLoadState=loaded\nFragmentPath={service_path}\nResult=success\n",
+ "",
+ )
+ return ("", "")
+
+ runner = FakeRunner(handlers={"systemctl": systemctl}, available={"systemctl"})
+ backend = SystemdBackend(runner)
+ jobs = backend.discover([Scope.USER])
+ assert len(jobs) == 1
+ job = jobs[0]
+ assert job.name == "backup"
+ assert job.managed is True
+ assert job.schedule.expression == "*-*-* 02:00:00"
+ assert job.command.argv == ("/usr/local/bin/backup", "/srv/data")
+ assert job.enabled is True
+ assert job.next_run is not None
+
+
+def test_plan_update_refuses_unmanaged() -> None:
+ runner = FakeRunner()
+ backend = SystemdBackend(runner)
+ unmanaged = replace(_job("certbot"), managed=False)
+ spec = JobSpec(
+ name="certbot",
+ backend=Backend.SYSTEMD,
+ scope=Scope.USER,
+ command=Command(argv=("/bin/true",)),
+ calendar=("*-*-* 01:00:00",),
+ )
+ with pytest.raises(SafetyRefusalError):
+ backend.plan_update(unmanaged, spec)
+
+
+def _managed_job(name: str = "backup", *, scope: Scope = Scope.USER, service_unit: str | None = None) -> ScheduledJob:
+ return replace(
+ _job(name),
+ scope=scope,
+ systemd=SystemdDetails(
+ timer_unit=f"schedls-{name}.timer",
+ service_unit=service_unit or f"schedls-{name}.service",
+ on_calendar=("*-*-* 02:00:00",),
+ ),
+ )
+
+
+def _spec(name: str = "backup") -> JobSpec:
+ return JobSpec(
+ name=name,
+ backend=Backend.SYSTEMD,
+ scope=Scope.USER,
+ command=Command(argv=("/bin/true",)),
+ calendar=("*-*-* 03:00:00",),
+ )
+
+
+def _analyze_runner() -> FakeRunner:
+ def analyze(argv, _input):
+ if "calendar" in argv:
+ return ("Normalized form: *-*-* 03:00:00\n", "")
+ return ("", "")
+
+ return FakeRunner(handlers={"systemd-analyze": analyze}, available={"systemd-analyze"})
+
+
+def test_plan_update_derives_unit_names(tmp_path, monkeypatch) -> None:
+ monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+ backend = SystemdBackend(_analyze_runner())
+ job = _managed_job(service_unit="../../../../tmp/evil.service")
+ plan = backend.plan_update(job, _spec())
+ expected_dir = os.path.join(str(tmp_path), "systemd", "user")
+ assert sorted(change.path for change in plan.files) == [
+ os.path.join(expected_dir, "schedls-backup.service"),
+ os.path.join(expected_dir, "schedls-backup.timer"),
+ ]
+ assert "evil" not in " ".join(change.path for change in plan.files)
+
+
+def test_verify_units_rejects_traversal() -> None:
+ backend = SystemdBackend(_analyze_runner())
+ with pytest.raises(SafetyRefusalError):
+ backend._verify_units({"../../evil.service": "content"})
+
+
+def test_unit_dir_rejects_relative_xdg(monkeypatch) -> None:
+ monkeypatch.setenv("XDG_CONFIG_HOME", "relative")
+ backend = SystemdBackend(FakeRunner())
+ with pytest.raises(SafetyRefusalError):
+ backend._unit_dir(Scope.USER)
+
+
+def test_plan_update_requires_scope(monkeypatch) -> None:
+ monkeypatch.setattr(os, "geteuid", lambda: 1000)
+ backend = SystemdBackend(_analyze_runner())
+ with pytest.raises(SafetyRefusalError):
+ backend.plan_update(_managed_job(scope=Scope.SYSTEM), _spec())
+
+
+def test_validate_spec_rejects_unsafe_calendar() -> None:
+ backend = SystemdBackend(FakeRunner())
+ spec = replace(_spec(), calendar=("-x",))
+ with pytest.raises(InvalidScheduleError):
+ backend._validate_spec(spec)
+
+
+def test_validate_spec_rejects_unsafe_jitter() -> None:
+ backend = SystemdBackend(_analyze_runner())
+ for jitter in ("5min\nExecStart=/bin/true", "-5min"):
+ with pytest.raises(InvalidScheduleError):
+ backend._validate_spec(replace(_spec(), jitter=jitter))
+
+
+def test_apply_rolls_back_on_keyboard_interrupt(tmp_path) -> None:
+ target = tmp_path / "schedls-backup.service"
+ raised = []
+
+ def systemctl(argv, _input):
+ if not raised:
+ raised.append(True)
+ raise KeyboardInterrupt
+ return ("", "")
+
+ runner = FakeRunner(handlers={"systemctl": systemctl}, available={"systemctl"})
+ backend = SystemdBackend(runner)
+ plan = Plan(backend="systemd", action="update")
+ plan.files = [FileChange(str(target), "content", mode=0o600)]
+ plan.commands = [CommandPlan(("systemctl", "daemon-reload"), "reload")]
+ plan.payload = {"scope": Scope.USER, "snapshots": {}}
+ with pytest.raises(KeyboardInterrupt):
+ backend.apply(plan)
+ assert not target.exists()
+
+
+def test_rollback_disables_timer_on_create_failure(tmp_path) -> None:
+ target = tmp_path / "schedls-backup.timer"
+
+ def systemctl(argv, _input):
+ if "daemon-reload" in argv:
+ return (1, "", "boom")
+ return ("", "")
+
+ runner = FakeRunner(handlers={"systemctl": systemctl}, available={"systemctl"})
+ backend = SystemdBackend(runner)
+ plan = Plan(backend="systemd", action="create")
+ plan.files = [FileChange(str(target), "content", mode=0o600)]
+ plan.commands = [CommandPlan(("systemctl", "daemon-reload"), "reload")]
+ plan.payload = {"scope": Scope.USER, "timer_unit": "schedls-backup.timer", "snapshots": {}}
+ with pytest.raises(OperationalError):
+ backend.apply(plan)
+ assert any("disable" in call[0] for call in runner.calls)
+ assert not target.exists()
+
+
+def test_logs_rejects_unsafe_service_unit() -> None:
+ backend = SystemdBackend(FakeRunner(available={"journalctl"}))
+ job = _managed_job(service_unit="--output=json.service")
+ with pytest.raises(SafetyRefusalError):
+ backend.logs(job, lines=5, since=None)
+
+
+def test_logs_returns_journal_text() -> None:
+ runner = FakeRunner(
+ handlers={"journalctl": lambda argv, _input: ("hello\n", "")},
+ available={"journalctl"},
+ )
+ backend = SystemdBackend(runner)
+ assert backend.logs(_managed_job(), lines=5, since="2 hours ago") == "hello\n"
+ argv = runner.calls[0][0]
+ assert "--since" in argv and "--lines=5" in argv
+
+
+def test_prefix_named_unit_without_marker_is_unmanaged(tmp_path) -> None:
+ timer_path = tmp_path / "schedls-backup.timer"
+ timer_path.write_text("[Unit]\n[Timer]\nOnCalendar=*-*-* 02:00:00\n")
+
+ def systemctl(argv, _input):
+ if "is-system-running" in argv:
+ return ("running\n", "")
+ if "list-unit-files" in argv or "list-units" in argv:
+ return ("schedls-backup.timer enabled\n", "")
+ if "show" in argv:
+ unit = argv[argv.index("show") + 1]
+ if unit.endswith(".timer"):
+ return (f"Id={unit}\nLoadState=loaded\nFragmentPath={timer_path}\n", "")
+ return ("", "")
+ return ("", "")
+
+ runner = FakeRunner(handlers={"systemctl": systemctl}, available={"systemctl"})
+ jobs = SystemdBackend(runner).discover([Scope.USER])
+ assert len(jobs) == 1
+ assert jobs[0].managed is False
+ assert jobs[0].name == "schedls-backup"
diff --git a/tests/unit/test_output.py b/tests/unit/test_output.py
new file mode 100644
index 0000000..644ab88
--- /dev/null
+++ b/tests/unit/test_output.py
@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import io
+import json
+from datetime import UTC, datetime
+
+from schedls.models import (
+ Backend,
+ Command,
+ CronDetails,
+ JobSource,
+ Schedule,
+ ScheduledJob,
+ ScheduleKind,
+ Scope,
+ SystemdDetails,
+)
+from schedls.output import Output, job_to_dict, jobs_document, sanitize_text
+
+
+def _systemd_job() -> ScheduledJob:
+ return ScheduledJob(
+ name="backup",
+ backend=Backend.SYSTEMD,
+ scope=Scope.USER,
+ managed=True,
+ enabled=True,
+ schedule=Schedule(ScheduleKind.CALENDAR, "*-*-* 02:00:00", ("*-*-* 02:00:00",)),
+ command=Command(argv=("/usr/local/bin/backup", "/srv/data")),
+ source=JobSource("systemd user timer", path="/home/u/.config/systemd/user/schedls-backup.timer"),
+ next_run=datetime(2026, 9, 25, 2, 0, tzinfo=UTC),
+ systemd=SystemdDetails(
+ timer_unit="schedls-backup.timer",
+ service_unit="schedls-backup.service",
+ persistent=True,
+ ),
+ )
+
+
+def _cron_job() -> ScheduledJob:
+ return ScheduledJob(
+ name="cron-3",
+ backend=Backend.CRON,
+ scope=Scope.USER,
+ managed=False,
+ enabled=None,
+ schedule=Schedule(ScheduleKind.CRON, "0 4 * * 0"),
+ command=Command(raw="/usr/local/bin/cleanup"),
+ source=JobSource("current user's crontab", line=3),
+ cron=CronDetails(expression="0 4 * * 0", line=3),
+ )
+
+
+def test_job_to_dict_systemd() -> None:
+ data = job_to_dict(_systemd_job())
+ assert data["name"] == "backup"
+ assert data["backend"] == "systemd"
+ assert data["managed"] is True
+ assert data["next_run"].endswith("+00:00")
+ assert data["systemd"]["persistent"] is True
+
+
+def test_job_to_dict_cron_missing_data_is_null() -> None:
+ data = job_to_dict(_cron_job())
+ assert data["next_run"] is None
+ assert data["last_run"] is None
+ assert data["enabled"] is None
+
+
+def test_jobs_document_schema_and_no_ansi() -> None:
+ document = jobs_document([_systemd_job(), _cron_job()], ["a warning"])
+ assert document["schema_version"] == 1
+ assert len(document["jobs"]) == 2
+ dumped = json.dumps(document)
+ assert "\x1b" not in dumped
+ assert "backup" in dumped
+
+
+def test_output_table_and_key_values() -> None:
+ stream = io.StringIO()
+ output = Output(json_mode=False, color="never", stdout=stream)
+ output.table(["NAME", "BACKEND"], [["backup", "systemd"], ["cleanup", "cron"]])
+ text = stream.getvalue()
+ assert "NAME" in text
+ assert "backup" in text
+ assert "\x1b" not in text
+
+
+def test_output_json_mode() -> None:
+ stream = io.StringIO()
+ output = Output(json_mode=True, color="never", stdout=stream)
+ output.emit_json({"schema_version": 1, "jobs": []})
+ assert json.loads(stream.getvalue())["schema_version"] == 1
+
+
+def test_sanitize_text_escapes_control_characters() -> None:
+ text = "a\x1b[31mred\x1b[0m\nb\tc\x00d\x7f"
+ assert sanitize_text(text) == "a\\x1b[31mred\\x1b[0m\nb\tc\\x00d\\x7f"
+
+
+def test_output_write_is_verbatim() -> None:
+ stream = io.StringIO()
+ output = Output(color="never", stdout=stream)
+ output.write("line one\nline two")
+ assert stream.getvalue() == "line one\nline two"
diff --git a/tests/unit/test_prompt.py b/tests/unit/test_prompt.py
new file mode 100644
index 0000000..97948f0
--- /dev/null
+++ b/tests/unit/test_prompt.py
@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import io
+
+import pytest
+
+from schedls.cli import _spec_for_edit, _spec_for_new, _wizard_edit, _wizard_new, build_parser
+from schedls.errors import ConfirmationRequiredError, InvalidScheduleError
+from schedls.models import (
+ Backend,
+ Command,
+ JobSource,
+ Schedule,
+ ScheduledJob,
+ ScheduleKind,
+ Scope,
+ SystemdDetails,
+)
+from schedls.output import Output
+from schedls.prompt import Prompter
+
+
+class FakeInput:
+ def __init__(self, answers: list[str]) -> None:
+ self.answers = list(answers)
+ self.prompts: list[str] = []
+
+ def __call__(self, label: str) -> str:
+ self.prompts.append(label)
+ if not self.answers:
+ raise EOFError
+ return self.answers.pop(0)
+
+
+class FakeStdin:
+ def __init__(self, *, isatty: bool) -> None:
+ self._isatty = isatty
+
+ def isatty(self) -> bool:
+ return self._isatty
+
+
+def make_prompter(answers: list[str], *, calendar_validator=None) -> tuple[Prompter, FakeInput]:
+ fake = FakeInput(answers)
+ output = Output(stdout=io.StringIO(), stderr=io.StringIO())
+ return Prompter(output=output, input_fn=fake, calendar_validator=calendar_validator), fake
+
+
+def _systemd_job() -> ScheduledJob:
+ return ScheduledJob(
+ name="backup",
+ backend=Backend.SYSTEMD,
+ scope=Scope.USER,
+ managed=True,
+ enabled=True,
+ schedule=Schedule(ScheduleKind.CALENDAR, "*-*-* 02:00:00"),
+ command=Command(argv=("/usr/local/bin/backup",)),
+ source=JobSource(detail="systemd user timer"),
+ systemd=SystemdDetails(on_calendar=("*-*-* 02:00:00",)),
+ )
+
+
+def test_text_requires_a_value() -> None:
+ prompter, fake = make_prompter(["", "backup"])
+ assert prompter.text("Name") == "backup"
+ assert len(fake.prompts) == 2
+
+
+def test_text_uses_default_on_blank() -> None:
+ prompter, _ = make_prompter([""])
+ assert prompter.text("Name", default="backup") == "backup"
+
+
+def test_optional_text() -> None:
+ prompter, _ = make_prompter(["", ""])
+ assert prompter.optional_text("Jitter") is None
+ assert prompter.optional_text("Jitter", default="5min") == "5min"
+
+
+def test_yes_no_rejects_unknown_answers() -> None:
+ prompter, _ = make_prompter(["maybe", "yes"])
+ assert prompter.yes_no("Continue?") is True
+
+
+def test_choice_by_number_and_default() -> None:
+ prompter, _ = make_prompter(["9", "2", ""])
+ options = [("daily", "Daily"), ("weekly", "Weekly")]
+ assert prompter.choice("Schedule:", options, default="daily") == "weekly"
+ assert prompter.choice("Schedule:", options, default="daily") == "daily"
+
+
+def test_command_builds_argv() -> None:
+ prompter, _ = make_prompter(["n", "/usr/bin/echo hello world"])
+ command = prompter.command()
+ assert command.shell is False
+ assert command.argv == ("/usr/bin/echo", "hello", "world")
+
+
+def test_command_shell_mode() -> None:
+ prompter, _ = make_prompter(["y", "echo hi | cat"])
+ command = prompter.command()
+ assert command.shell is True
+ assert command.raw == "echo hi | cat"
+
+
+def test_environment_collects_valid_entries() -> None:
+ prompter, _ = make_prompter(["A=1", "1BAD=2", "B=x=y", ""])
+ assert prompter.environment() == ["A=1", "B=x=y"]
+
+
+def test_schedule_daily_reprompts_on_bad_time() -> None:
+ prompter, _ = make_prompter(["", "25:00", "02:30"])
+ assert prompter.schedule(Backend.SYSTEMD) == {"daily": "02:30"}
+
+
+def test_schedule_weekly_and_monthly() -> None:
+ prompter, _ = make_prompter(["3", "Mon", "02:00"])
+ assert prompter.schedule(Backend.SYSTEMD) == {"weekly": ["Mon", "02:00"]}
+ prompter, _ = make_prompter(["4", "15", "06:00"])
+ assert prompter.schedule(Backend.SYSTEMD) == {"monthly": ["15", "06:00"]}
+
+
+def test_schedule_custom_systemd_validates() -> None:
+ def validator(expression: str) -> None:
+ if expression != "daily":
+ raise InvalidScheduleError("bad expression")
+
+ prompter, _ = make_prompter(["5", "bogus", "daily"], calendar_validator=validator)
+ assert prompter.schedule(Backend.SYSTEMD) == {"calendar": ["daily"]}
+
+
+def test_schedule_custom_cron() -> None:
+ prompter, _ = make_prompter(["5", "0 4 * * *"])
+ assert prompter.schedule(Backend.CRON) == {"cron_expr": "0 4 * * *"}
+
+
+def test_require_terminal_rejects_non_tty(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr("sys.stdin", FakeStdin(isatty=False))
+ prompter, _ = make_prompter([])
+ with pytest.raises(ConfirmationRequiredError):
+ prompter.require_terminal()
+
+
+def test_eof_raises_confirmation_required() -> None:
+ prompter, _ = make_prompter([])
+ with pytest.raises(ConfirmationRequiredError):
+ prompter.text("Name")
+
+
+def test_wizard_new_systemd(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr("sys.stdin", FakeStdin(isatty=True))
+ args = build_parser().parse_args(["new", "-i"])
+ answers = ["backup", "", "n", "/usr/local/bin/backup /srv/data", "", "02:00", "n"]
+ prompter, _ = make_prompter(answers)
+ args, tail = _wizard_new(args, [], prompter)
+ spec = _spec_for_new(args, tail)
+ assert spec.name == "backup"
+ assert spec.backend is Backend.SYSTEMD
+ assert spec.calendar == ("*-*-* 02:00:00",)
+ assert spec.command.argv == ("/usr/local/bin/backup", "/srv/data")
+
+
+def test_wizard_new_cron(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr("sys.stdin", FakeStdin(isatty=True))
+ args = build_parser().parse_args(["new", "-i"])
+ answers = ["cleanup", "2", "n", "/usr/local/bin/cleanup", "", "04:00"]
+ prompter, _ = make_prompter(answers)
+ args, tail = _wizard_new(args, [], prompter)
+ spec = _spec_for_new(args, tail)
+ assert spec.backend is Backend.CRON
+ assert spec.cron_expression == "0 4 * * *"
+
+
+def test_wizard_new_skips_provided_fields(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr("sys.stdin", FakeStdin(isatty=True))
+ args = build_parser().parse_args(["new", "backup", "-i", "--timer", "--daily", "02:00"])
+ prompter, fake = make_prompter(["n"])
+ args, tail = _wizard_new(args, ["/bin/true"], prompter)
+ spec = _spec_for_new(args, tail)
+ assert spec.calendar == ("*-*-* 02:00:00",)
+ assert fake.prompts == ["Set advanced timer options? [y/N] "]
+
+
+def test_wizard_edit_changes_schedule(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr("sys.stdin", FakeStdin(isatty=True))
+ job = _systemd_job()
+ args = build_parser().parse_args(["edit", "backup", "-i"])
+ answers = ["n", "y", "", "03:00", "n"]
+ prompter, _ = make_prompter(answers)
+ args, tail = _wizard_edit(job, args, [], prompter)
+ spec = _spec_for_edit(job, args, tail)
+ assert spec.calendar == ("*-*-* 03:00:00",)
+
+
+def test_wizard_edit_keeps_changes_optional(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr("sys.stdin", FakeStdin(isatty=True))
+ job = _systemd_job()
+ args = build_parser().parse_args(["edit", "backup", "-i"])
+ prompter, _ = make_prompter(["n", "n", "n"])
+ args, tail = _wizard_edit(job, args, [], prompter)
+ spec = _spec_for_edit(job, args, tail)
+ assert spec.calendar == ("*-*-* 02:00:00",)
+ assert tail == []
diff --git a/tests/unit/test_renderers_cron.py b/tests/unit/test_renderers_cron.py
new file mode 100644
index 0000000..67607fc
--- /dev/null
+++ b/tests/unit/test_renderers_cron.py
@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import json
+import shlex
+import subprocess
+import sys
+
+import pytest
+
+from schedls.errors import InvalidScheduleError, SafetyRefusalError
+from schedls.models import Command
+from schedls.renderers import cron as renderer
+
+NASTY_ARGS = [
+ "plain",
+ "a b",
+ "a\tb",
+ 'a"b',
+ "a'b",
+ "a\\b",
+ "a\\\\b",
+ "$HOME",
+ "$(touch /tmp/pwned)",
+ "`touch /tmp/pwned`",
+ "%",
+ "100%",
+ "a%b",
+ "a\\%b",
+ "a\\\\%b",
+ "",
+ " leading",
+ "trailing ",
+ "semi;colon",
+ "pipe|cmd",
+ "new&line",
+ ">out",
+ "unicode-\u00e9\u4e2d\U0001f600",
+]
+
+
+def cron_resolve(text: str) -> str:
+ """Emulate Cronie's ``%`` processing of a command field."""
+ out: list[str] = []
+ index = 0
+ while index < len(text):
+ char = text[index]
+ if char == "\\" and index + 1 < len(text) and text[index + 1] == "%":
+ out.append("%")
+ index += 2
+ continue
+ if char == "%":
+ out.append("\n")
+ index += 1
+ continue
+ out.append(char)
+ index += 1
+ return "".join(out)
+
+
+def test_escape_percent() -> None:
+ assert renderer.escape_percent("100%") == "100\\%"
+ assert renderer.escape_percent("a\\%b") == "a\\\\%b"
+
+
+def test_render_command_argv() -> None:
+ rendered = renderer.render_command(Command(argv=("/usr/local/bin/backup", "/srv/My Data")))
+ assert rendered == "/usr/local/bin/backup '/srv/My Data'"
+
+
+def test_render_command_shell() -> None:
+ rendered = renderer.render_command(Command(shell=True, raw="echo 50% > /tmp/x"))
+ assert rendered == "echo 50\\% > /tmp/x"
+
+
+def test_expression_percent_not_double_escaped() -> None:
+ line = renderer.render_line("0 2 * * *", Command(argv=("/bin/echo", "a%b")))
+ assert line == "0 2 * * * /bin/echo a\\%b"
+
+
+@pytest.mark.parametrize(
+ "bad",
+ ["", "0 2 * *", "0 2 * * * *", "60 2 * * *", "0 25 * * *", "0 2 32 * *", "@bogus", "a b c d e"],
+)
+def test_invalid_expressions(bad: str) -> None:
+ with pytest.raises(InvalidScheduleError):
+ renderer.validate_expression(bad)
+
+
+@pytest.mark.parametrize(
+ "good",
+ ["* * * * *", "0 2 * * *", "*/5 * * * *", "0 2 * * 1-5", "0 2 1,15 * 5", "@daily", "@reboot"],
+)
+def test_valid_expressions(good: str) -> None:
+ assert renderer.validate_expression(good)
+
+
+@pytest.mark.parametrize("arg", NASTY_ARGS)
+def test_argv_round_trip_through_shell(tmp_path, arg: str) -> None:
+ dump = tmp_path / "dump.py"
+ dump.write_text("import json,sys\nopen(sys.argv[1],'w').write(json.dumps(sys.argv[2:]))\n")
+ out = tmp_path / "out.json"
+ command = Command(argv=(sys.executable, str(dump), str(out), arg))
+ serialized = renderer.render_command(command)
+ resolved = cron_resolve(serialized)
+ subprocess.run(["/bin/sh", "-c", resolved], check=True)
+ received = json.loads(out.read_text())
+ assert received == [arg]
+
+
+def test_no_command_injection(tmp_path) -> None:
+ marker = tmp_path / "pwned"
+ command = Command(argv=("/bin/true", f"x; touch {marker}", f"$(touch {marker})", f"`touch {marker}`"))
+ resolved = cron_resolve(renderer.render_command(command))
+ subprocess.run(["/bin/sh", "-c", resolved], check=True)
+ assert not marker.exists()
+
+
+def test_newline_rejected() -> None:
+ with pytest.raises(SafetyRefusalError):
+ renderer.render_command(Command(argv=("/bin/echo", "a\nb")))
+
+
+def test_managed_block() -> None:
+ block = renderer.render_block("backup", ["0 2 * * * /bin/true"])
+ assert block == ("# schedls:begin name=backup\n0 2 * * * /bin/true\n# schedls:end name=backup\n")
+
+
+def test_shlex_reference() -> None:
+ assert shlex.quote("a b") == "'a b'"
diff --git a/tests/unit/test_renderers_systemd.py b/tests/unit/test_renderers_systemd.py
new file mode 100644
index 0000000..73bc226
--- /dev/null
+++ b/tests/unit/test_renderers_systemd.py
@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from schedls.errors import SafetyRefusalError
+from schedls.models import Backend, Command, JobSpec, Scope
+from schedls.renderers import systemd as renderer
+
+FIXTURES = Path(__file__).resolve().parents[1] / "fixtures" / "systemd"
+
+NASTY_ARGS = [
+ "plain",
+ "a b",
+ "a\tb",
+ 'a"b',
+ "a'b",
+ "a\\b",
+ "a\\\\b",
+ "$HOME",
+ "$$",
+ "$(touch /tmp/pwned)",
+ "`touch /tmp/pwned`",
+ "%n",
+ "%%",
+ "%i",
+ "",
+ " leading",
+ "trailing ",
+ "semi;colon",
+ "pipe|cmd",
+ "new&line",
+ "unicode-\u00e9\u4e2d\U0001f600",
+ "-dash",
+ "@at",
+ "!bang",
+]
+
+
+def test_quote_basic() -> None:
+ assert renderer.quote_systemd_arg("plain") == '"plain"'
+ assert renderer.quote_systemd_arg("a b") == '"a b"'
+ assert renderer.quote_systemd_arg("") == '""'
+ assert renderer.quote_systemd_arg("$HOME") == '"$$HOME"'
+ assert renderer.quote_systemd_arg("%n") == '"%%n"'
+ assert renderer.quote_systemd_arg('a"b') == '"a\\"b"'
+ assert renderer.quote_systemd_arg("a\\b") == '"a\\\\b"'
+
+
+@pytest.mark.parametrize("arg", NASTY_ARGS)
+def test_argv_round_trip(arg: str) -> None:
+ command = Command(argv=(arg,))
+ rendered = renderer.render_exec_start(command)
+ value = rendered.split("=", 1)[1]
+ parsed = renderer.parse_exec_start(value)
+ assert parsed.argv == (arg,)
+
+
+def test_multi_argv_round_trip() -> None:
+ command = Command(argv=tuple(NASTY_ARGS))
+ value = renderer.render_exec_start(command).split("=", 1)[1]
+ assert renderer.parse_exec_start(value).argv == tuple(NASTY_ARGS)
+
+
+def test_shell_mode_round_trip() -> None:
+ command = Command(shell=True, raw="generate-report | gzip > /srv/report.gz")
+ value = renderer.render_exec_start(command).split("=", 1)[1]
+ parsed = renderer.parse_exec_start(value)
+ assert parsed.shell is True
+ assert parsed.raw == "generate-report | gzip > /srv/report.gz"
+
+
+def test_shell_mode_quotes_script() -> None:
+ command = Command(shell=True, raw="echo $HOME > /tmp/x")
+ rendered = renderer.render_exec_start(command)
+ assert rendered.startswith('ExecStart=/bin/sh -c "')
+ assert "$$HOME" in rendered
+
+
+@pytest.mark.parametrize("bad", ["a\nb", "a\rb", "a\x00b"])
+def test_control_characters_rejected(bad: str) -> None:
+ with pytest.raises(SafetyRefusalError):
+ renderer.render_exec_start(Command(argv=(bad,)))
+
+
+def test_golden_service() -> None:
+ spec = JobSpec(
+ name="backup",
+ backend=Backend.SYSTEMD,
+ scope=Scope.USER,
+ command=Command(argv=("/usr/local/bin/backup", "/srv/data")),
+ calendar=("*-*-* 02:00:00",),
+ persistent=True,
+ )
+ files = renderer.render_units(spec, service_unit="schedls-backup.service", timer_unit="schedls-backup.timer")
+ assert files["schedls-backup.service"] == (FIXTURES / "basic.service").read_text()
+ assert files["schedls-backup.timer"] == (FIXTURES / "basic.timer").read_text()
+
+
+def test_timer_multiple_calendars() -> None:
+ spec = JobSpec(
+ name="multi",
+ backend=Backend.SYSTEMD,
+ scope=Scope.USER,
+ command=Command(argv=("/bin/true",)),
+ calendar=("Mon..Fri 02:00:00", "Sat,Sun 04:00:00"),
+ )
+ timer = renderer.render_timer(spec, "schedls-multi.timer", "schedls-multi.service")
+ assert "OnCalendar=Mon..Fri 02:00:00" in timer
+ assert "OnCalendar=Sat,Sun 04:00:00" in timer
diff --git a/tests/unit/test_security.py b/tests/unit/test_security.py
new file mode 100644
index 0000000..de60a4f
--- /dev/null
+++ b/tests/unit/test_security.py
@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import os
+import stat
+
+import pytest
+
+from schedls.errors import InvalidNameError, SafetyRefusalError
+from schedls.runner import CommandRunner
+from schedls.security import (
+ atomic_write_text,
+ check_replaceable,
+ check_trusted_directory,
+ is_managed_unit,
+ is_safe_unit_name,
+ remove_file,
+ resolve_helper,
+ unit_name,
+ validate_managed_unit_name,
+ validate_name,
+)
+
+
+@pytest.mark.parametrize(
+ "name",
+ ["backup", "postgres-backup", "report.daily", "sync_home", "a", "A1._-", "x" * 64],
+)
+def test_valid_names(name: str) -> None:
+ assert validate_name(name) == name
+
+
+@pytest.mark.parametrize(
+ "name",
+ ["", "../foo", "foo/bar", "name with spaces", "$(command)", ".hidden", "-lead", "x" * 65, "foo\nbar", "foo\n"],
+)
+def test_invalid_names(name: str) -> None:
+ with pytest.raises(InvalidNameError):
+ validate_name(name)
+
+
+def test_unit_name() -> None:
+ assert unit_name("backup", "timer") == "schedls-backup.timer"
+ assert is_managed_unit("schedls-backup.timer")
+ assert not is_managed_unit("certbot.timer")
+ with pytest.raises(InvalidNameError):
+ unit_name("../evil", "timer")
+
+
+def test_atomic_write_and_remove(tmp_path) -> None:
+ target = tmp_path / "file.txt"
+ atomic_write_text(str(target), "hello\n", mode=0o600)
+ assert target.read_text() == "hello\n"
+ assert stat.S_IMODE(target.stat().st_mode) == 0o600
+ assert remove_file(str(target)) is True
+ assert not target.exists()
+ assert remove_file(str(target)) is False
+
+
+def test_atomic_write_refuses_symlink(tmp_path) -> None:
+ real = tmp_path / "real.txt"
+ real.write_text("secret")
+ link = tmp_path / "link.txt"
+ link.symlink_to(real)
+ with pytest.raises(SafetyRefusalError):
+ atomic_write_text(str(link), "overwrite")
+ assert real.read_text() == "secret"
+
+
+def test_remove_refuses_symlink(tmp_path) -> None:
+ real = tmp_path / "real.txt"
+ real.write_text("secret")
+ link = tmp_path / "link.txt"
+ link.symlink_to(real)
+ with pytest.raises(SafetyRefusalError):
+ remove_file(str(link))
+
+
+def test_check_replaceable_ownership(tmp_path) -> None:
+ target = tmp_path / "file.txt"
+ target.write_text("x")
+ check_replaceable(str(target), expected_uid=os.getuid())
+ with pytest.raises(SafetyRefusalError):
+ check_replaceable(str(target), expected_uid=os.getuid() + 99999)
+
+
+def test_resolve_helper_rejects_missing() -> None:
+ assert resolve_helper("definitely-not-a-real-helper-xyz") is None
+
+
+def test_resolve_helper_rejects_world_writable_dir(tmp_path, monkeypatch) -> None:
+ helper_dir = tmp_path / "bin"
+ helper_dir.mkdir()
+ helper = helper_dir / "evilhelper"
+ helper.write_text("#!/bin/sh\ntrue\n")
+ helper.chmod(0o755)
+ helper_dir.chmod(0o777)
+ monkeypatch.setenv("PATH", str(helper_dir))
+ assert resolve_helper("evilhelper") is None
+
+
+def test_resolve_helper_rejects_group_writable_file(tmp_path, monkeypatch) -> None:
+ helper_dir = tmp_path / "bin"
+ helper_dir.mkdir()
+ helper = helper_dir / "evilhelper"
+ helper.write_text("#!/bin/sh\ntrue\n")
+ helper.chmod(0o775)
+ monkeypatch.setenv("PATH", str(helper_dir))
+ assert resolve_helper("evilhelper") is None
+
+
+def test_resolve_helper_rejects_user_owned_dir_when_root(tmp_path, monkeypatch) -> None:
+ helper_dir = tmp_path / "bin"
+ helper_dir.mkdir()
+ helper = helper_dir / "evilhelper"
+ helper.write_text("#!/bin/sh\ntrue\n")
+ helper.chmod(0o755)
+ monkeypatch.setenv("PATH", str(helper_dir))
+ monkeypatch.setattr(os, "geteuid", lambda: 0)
+ assert resolve_helper("evilhelper") is None
+
+
+def test_resolve_helper_accepts_own_dir_when_not_root(tmp_path, monkeypatch) -> None:
+ helper_dir = tmp_path / "bin"
+ helper_dir.mkdir()
+ helper = helper_dir / "goodhelper"
+ helper.write_text("#!/bin/sh\ntrue\n")
+ helper.chmod(0o755)
+ monkeypatch.setenv("PATH", str(helper_dir))
+ monkeypatch.setattr(os, "geteuid", lambda: 4242)
+ assert resolve_helper("goodhelper") == str(helper)
+
+
+def test_runner_refuses_untrusted_absolute_helper(tmp_path, monkeypatch) -> None:
+ helper = tmp_path / "evil"
+ helper.write_text("#!/bin/sh\ntrue\n")
+ helper.chmod(0o755)
+ monkeypatch.setattr(os, "geteuid", lambda: 0)
+ with pytest.raises(SafetyRefusalError):
+ CommandRunner().run([str(helper)])
+
+
+def test_runner_refuses_relative_executable() -> None:
+ with pytest.raises(SafetyRefusalError):
+ CommandRunner().run(["bin/evil"])
+
+
+def test_check_trusted_directory_owner_and_mode(tmp_path) -> None:
+ check_trusted_directory(str(tmp_path), expected_uid=os.getuid())
+ with pytest.raises(SafetyRefusalError):
+ check_trusted_directory(str(tmp_path), expected_uid=os.getuid() + 99999)
+ tmp_path.chmod(0o777)
+ with pytest.raises(SafetyRefusalError):
+ check_trusted_directory(str(tmp_path), expected_uid=os.getuid())
+
+
+def test_validate_managed_unit_name() -> None:
+ assert validate_managed_unit_name("schedls-backup.timer") == "schedls-backup.timer"
+ assert validate_managed_unit_name("schedls-a_b.service") == "schedls-a_b.service"
+ for unit in (
+ "../../etc/passwd",
+ "schedls-../x.timer",
+ "certbot.timer",
+ "schedls-x.timer/../y",
+ "schedls-x.timer\n",
+ ):
+ with pytest.raises(SafetyRefusalError):
+ validate_managed_unit_name(unit)
+
+
+def test_is_safe_unit_name() -> None:
+ assert is_safe_unit_name("certbot.service")
+ assert is_safe_unit_name("foo@bar.timer")
+ assert not is_safe_unit_name("--output=json")
+ assert not is_safe_unit_name("../../evil.service")
+ assert not is_safe_unit_name("unit with spaces.service")
diff --git a/tests/unit/test_timefmt.py b/tests/unit/test_timefmt.py
new file mode 100644
index 0000000..2211122
--- /dev/null
+++ b/tests/unit/test_timefmt.py
@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta, timezone
+
+import pytest
+
+from schedls import timefmt
+
+
+@pytest.mark.parametrize(
+ ("value", "seconds"),
+ [
+ ("1s", 1.0),
+ ("30m", 1800.0),
+ ("1h", 3600.0),
+ ("2h30m", 9000.0),
+ ("1d", 86400.0),
+ ("1w", 604800.0),
+ ("500ms", 0.5),
+ ("1min", 60.0),
+ ],
+)
+def test_duration_seconds(value: str, seconds: float) -> None:
+ assert timefmt.duration_seconds(value) == pytest.approx(seconds)
+
+
+@pytest.mark.parametrize("bad", ["", "abc", "1x", "h", "1h2x"])
+def test_invalid_duration(bad: str) -> None:
+ with pytest.raises(ValueError):
+ timefmt.duration_seconds(bad)
+ assert not timefmt.is_valid_duration(bad)
+
+
+def test_parse_microseconds() -> None:
+ parsed = timefmt.parse_systemd_timestamp("1758700800000000")
+ assert parsed is not None
+ assert parsed.year == 2025
+
+
+def test_parse_pretty() -> None:
+ parsed = timefmt.parse_systemd_timestamp("Thu 2026-09-24 06:49:28 BST")
+ assert parsed is not None
+ assert (parsed.year, parsed.month, parsed.day) == (2026, 9, 24)
+ assert parsed.tzinfo is not None
+
+
+def test_parse_placeholders() -> None:
+ assert timefmt.parse_systemd_timestamp("") is None
+ assert timefmt.parse_systemd_timestamp("n/a") is None
+ assert timefmt.parse_systemd_timestamp("0") is None
+
+
+def test_format_datetime_round_trip_zone() -> None:
+ dt = datetime(2026, 9, 25, 2, 0, 0, tzinfo=timezone(timedelta(hours=1)))
+ text = timefmt.format_datetime(dt)
+ assert text.startswith("Fri 25 Sep 2026 02:00:00")
+
+
+def test_format_short_relative() -> None:
+ now = datetime(2026, 9, 24, 12, 0, tzinfo=UTC)
+ today = datetime(2026, 9, 24, 18, 0, tzinfo=UTC)
+ tomorrow = datetime(2026, 9, 25, 3, 0, tzinfo=UTC)
+ assert timefmt.format_short(today, now=now, utc=True) == "today 18:00"
+ assert timefmt.format_short(tomorrow, now=now, utc=True) == "tomorrow 03:00"
+
+
+def test_isoformat_has_offset() -> None:
+ dt = datetime(2026, 9, 25, 2, 0, tzinfo=UTC)
+ assert timefmt.isoformat(dt).endswith("+00:00")