runspec-scheduler 0.1.0__tar.gz

runspec_scheduler-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_scheduler-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `runspec-scheduler` are documented here.
+
+## [0.1.0]
+
+Initial release.
+
+- A long-running per-venv scheduler daemon (`systemctl --user`) that runs runnables
+  installed in its own venv on a cron/interval cadence — independent of any desktop
+  console.
+- Itself a runspec runnable (`discoverable = false`) with verbs: `run` (daemon),
+  `add`, `remove`, `list`, `run-now`, `install-service`.
+- Venv-scoped config at `{sys.prefix}/runspec_scheduler.toml` (override with
+  `--config` / `$RUNSPEC_SCHEDULER_CONFIG`); atomic writes; mtime hot-reload.
+- Timing (`cron` / `every`) mirrors runspec-console's schedule semantics exactly,
+  pinned by a parity test.
+- Rotating audit log at `{sys.prefix}/logs/scheduler.log`.
+- Credential support for `run_as` runnables via `RUNSPEC_ENV_FILE`: a 600 env file
+  owned by the `run_as` account (written with the secret on stdin, never argv); the
+  daemon points `RUNSPEC_ENV_FILE` at it and escalates to `run_as` when firing.

runspec_scheduler-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: runspec-scheduler
+Version: 0.1.0
+Summary: Cron-style scheduler service for runspec runnables installed in one venv
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: apscheduler<4,>=3.10
+Requires-Dist: runspec>=0.48.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# runspec-scheduler
+
+**Cron, but limited to runspec runnables installed in one venv.**
+
+A long-running per-venv scheduler daemon (`systemctl --user`) that runs runnables
+installed in *its own venv* on a cron/interval cadence — independent of any desktop
+console. It is itself a runspec runnable, so `runspec-console` can detect it and
+manage its schedules over SSH, but `discoverable = false` keeps it out of the Forms
+tab / `runspec serve` MCP surface.
+
+## Why
+
+A console-driven schedule only fires while the desktop console is open, and it's
+per-operator. `runspec-scheduler` gives you **shared, always-on** schedules that live
+on the host and run whether or not a console is connected.
+
+## Install
+
+```bash
+# Into the same venv whose runnables you want to schedule:
+pip install runspec-scheduler
+
+# Install + enable the systemd --user service for this venv:
+runspec-scheduler install-service
+loginctl enable-linger "$USER"     # survive logout
+```
+
+`install-service` writes `~/.config/systemd/user/runspec-scheduler-<venv>.service`
+(one daemon per venv) and runs `systemctl --user enable --now`. To do it by hand, see
+`deploy/runspec-scheduler.service`.
+
+## Use
+
+```bash
+runspec-scheduler add --id nightly --runnable backup --cron '0 2 * * *'
+runspec-scheduler add --id poll   --runnable healthcheck --every 15m --args '{"level":"warn"}'
+runspec-scheduler list
+runspec-scheduler run-now --id poll
+runspec-scheduler remove --id poll
+```
+
+- Exactly one of `--cron` (5-field cron) or `--every` (`15m` / `1h` / `1d`).
+- `--args` is a JSON object passed to the target runnable.
+- Adding/removing a schedule hot-reloads the running daemon (mtime poll, ≤ 5s).
+
+## Config
+
+Schedules live in `{venv}/runspec_scheduler.toml` (override with `--config` or
+`$RUNSPEC_SCHEDULER_CONFIG`). The daemon keeps a rotating audit log at
+`{venv}/logs/scheduler.log`; live logs via `journalctl --user -u runspec-scheduler-<venv> -f`.
+
+## Credentials (`run_as` runnables)
+
+`runspec-console` can attach service-account credentials to a remote schedule. For a
+runnable that declares `run_as`, the selected credentials are written to a **600 env
+file owned by the `run_as` account** in that account's home; the daemon points
+`RUNSPEC_ENV_FILE` at it and escalates to `run_as` when firing. Credentials are never
+placed on a command line. This requires the daemon/SSH user to have passwordless
+`sudo -u <run_as>` (the same precondition as running that `run_as` runnable at all).
+
+Runnables **without** `run_as` run as the daemon's own user with the daemon's
+environment (systemd `EnvironmentFile`) — no console credential injection.

runspec_scheduler-0.1.0/README.md

@@ -0,0 +1,62 @@
+# runspec-scheduler
+
+**Cron, but limited to runspec runnables installed in one venv.**
+
+A long-running per-venv scheduler daemon (`systemctl --user`) that runs runnables
+installed in *its own venv* on a cron/interval cadence — independent of any desktop
+console. It is itself a runspec runnable, so `runspec-console` can detect it and
+manage its schedules over SSH, but `discoverable = false` keeps it out of the Forms
+tab / `runspec serve` MCP surface.
+
+## Why
+
+A console-driven schedule only fires while the desktop console is open, and it's
+per-operator. `runspec-scheduler` gives you **shared, always-on** schedules that live
+on the host and run whether or not a console is connected.
+
+## Install
+
+```bash
+# Into the same venv whose runnables you want to schedule:
+pip install runspec-scheduler
+
+# Install + enable the systemd --user service for this venv:
+runspec-scheduler install-service
+loginctl enable-linger "$USER"     # survive logout
+```
+
+`install-service` writes `~/.config/systemd/user/runspec-scheduler-<venv>.service`
+(one daemon per venv) and runs `systemctl --user enable --now`. To do it by hand, see
+`deploy/runspec-scheduler.service`.
+
+## Use
+
+```bash
+runspec-scheduler add --id nightly --runnable backup --cron '0 2 * * *'
+runspec-scheduler add --id poll   --runnable healthcheck --every 15m --args '{"level":"warn"}'
+runspec-scheduler list
+runspec-scheduler run-now --id poll
+runspec-scheduler remove --id poll
+```
+
+- Exactly one of `--cron` (5-field cron) or `--every` (`15m` / `1h` / `1d`).
+- `--args` is a JSON object passed to the target runnable.
+- Adding/removing a schedule hot-reloads the running daemon (mtime poll, ≤ 5s).
+
+## Config
+
+Schedules live in `{venv}/runspec_scheduler.toml` (override with `--config` or
+`$RUNSPEC_SCHEDULER_CONFIG`). The daemon keeps a rotating audit log at
+`{venv}/logs/scheduler.log`; live logs via `journalctl --user -u runspec-scheduler-<venv> -f`.
+
+## Credentials (`run_as` runnables)
+
+`runspec-console` can attach service-account credentials to a remote schedule. For a
+runnable that declares `run_as`, the selected credentials are written to a **600 env
+file owned by the `run_as` account** in that account's home; the daemon points
+`RUNSPEC_ENV_FILE` at it and escalates to `run_as` when firing. Credentials are never
+placed on a command line. This requires the daemon/SSH user to have passwordless
+`sudo -u <run_as>` (the same precondition as running that `run_as` runnable at all).
+
+Runnables **without** `run_as` run as the daemon's own user with the daemon's
+environment (systemd `EnvironmentFile`) — no console credential injection.

runspec_scheduler-0.1.0/deploy/runspec-scheduler.service

@@ -0,0 +1,29 @@
+# systemd --user unit for the runspec scheduler daemon.
+#
+# This is a template. `runspec-scheduler install-service` writes a per-venv copy
+# named runspec-scheduler-<venv>.service with ExecStart pointing at this venv's
+# binary — prefer that over copying this by hand. To install manually:
+#
+#   cp deploy/runspec-scheduler.service \
+#      ~/.config/systemd/user/runspec-scheduler-<venv>.service
+#   # edit ExecStart to your venv's bin/runspec-scheduler
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now runspec-scheduler-<venv>
+#   loginctl enable-linger "$USER"      # keep it running after logout
+
+[Unit]
+Description=runspec scheduler
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h
+# Point this at your venv's binary, e.g. %h/venvs/ops/bin/runspec-scheduler
+ExecStart=%h/.local/bin/runspec-scheduler run
+EnvironmentFile=-%h/.config/runspec-scheduler/runspec-scheduler.env
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target

runspec_scheduler-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-scheduler"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Cron-style scheduler service for runspec runnables installed in one venv"
+readme = "README.md"
+license = "MIT"
+dependencies = [
+    # 0.48.0 for the `discoverable` boolean + serve leaf globals used by the console.
+    "runspec>=0.48.0",
+    # APScheduler drives the cron/interval timing. This package's whole reason to
+    # exist is scheduling, so it's a hard dependency (unlike runspec-console, which
+    # keeps it optional under the [schedule] extra).
+    "apscheduler>=3.10,<4",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.scripts]
+# Entry point name MUST match the runnable name in runspec.toml.
+runspec-scheduler = "runspec_scheduler.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "ruff==0.15.20",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[[tool.mypy.overrides]]
+# APScheduler ships no type stubs; tomli is the 3.10-only TOML reader.
+module = ["apscheduler.*", "tomli"]
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_scheduler-0.1.0/runspec_scheduler/__init__.py

@@ -0,0 +1,36 @@
+"""runspec-scheduler — a cron-style scheduler service for runspec runnables.
+
+A long-running per-venv daemon (``systemctl --user``) that runs runnables
+installed in *its own venv* on a cron/interval cadence, independent of any
+desktop console. It is itself a runspec runnable with management verbs
+(``run`` / ``add`` / ``remove`` / ``list`` / ``run-now`` / ``install-service``).
+
+Public API (for corporate wrappers / tests): the pure config + timing helpers,
+which have no runspec-console dependency.
+"""
+
+from __future__ import annotations
+
+from .config import (
+    ScheduleEntry,
+    config_path,
+    load_schedules,
+    read_config,
+    upsert_schedule,
+    write_schedules,
+)
+from .timing import When, next_fire_time, parse_when
+
+__all__ = [
+    "ScheduleEntry",
+    "When",
+    "config_path",
+    "load_schedules",
+    "next_fire_time",
+    "parse_when",
+    "read_config",
+    "upsert_schedule",
+    "write_schedules",
+]
+
+__version__ = "0.1.0"

runspec_scheduler-0.1.0/runspec_scheduler/cli.py

@@ -0,0 +1,186 @@
+"""cli.py — the `runspec-scheduler` entry point.
+
+One binary, several verbs. ``rs.parse("runspec-scheduler")`` resolves the
+subcommand + args; we dispatch on ``spec.runspec_command``.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import runspec as rs
+
+from .config import ScheduleEntry, config_path, load_schedules, remove_schedule, upsert_schedule
+from .daemon import configure_logging, run_daemon
+from .discovery import resolve_target
+from .envfile import capture_env, remove_env_file, write_env_file
+from .runner import run_runnable, venv_name
+from .timing import next_fire_time, parse_when
+
+
+def _opt(arg: Any) -> Any:
+    """Underlying value of a runspec ``Arg``; '' / None → None."""
+    value = getattr(arg, "value", arg)
+    if value is None:
+        return None
+    if isinstance(value, str) and not value.strip():
+        return None
+    return value
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload))
+
+
+def _parse_json_arg(raw: Any, what: str) -> Any:
+    if raw is None:
+        return None
+    try:
+        return json.loads(str(raw))
+    except json.JSONDecodeError as exc:
+        _emit({"error": f"invalid JSON for {what}: {exc}"})
+        sys.exit(2)
+
+
+def _cfg_path(spec: rs.RunSpec) -> Path:
+    return config_path(_opt(spec.config))
+
+
+def _cmd_run(spec: rs.RunSpec) -> None:
+    configure_logging()
+    run_daemon(_cfg_path(spec), reload_interval=int(spec.reload_interval.value))
+
+
+def _cmd_add(spec: rs.RunSpec) -> None:
+    path = _cfg_path(spec)
+    sid = str(spec.id.value)
+    runnable = str(spec.runnable.value)
+    when = parse_when(
+        {
+            "cron": _opt(spec.cron) or "",
+            "every": _opt(spec.every) or "",
+            "timezone": _opt(spec.timezone) or "",
+        }
+    )
+    args = _parse_json_arg(_opt(spec.args), "--args") or {}
+    if not isinstance(args, dict):
+        _emit({"error": "--args must be a JSON object"})
+        sys.exit(2)
+
+    target = resolve_target(runnable)
+    if target is None:
+        _emit({"error": f"runnable '{runnable}' is not installed in this venv ({venv_name()})"})
+        sys.exit(2)
+
+    cred_vars = _parse_json_arg(_opt(spec.cred_vars), "--cred-vars")
+    env_file = ""
+    if cred_vars:
+        if not isinstance(cred_vars, list):
+            _emit({"error": "--cred-vars must be a JSON array of variable names"})
+            sys.exit(2)
+        if not target.run_as:
+            _emit({"error": f"credentials require a run_as runnable, but '{runnable}' declares none"})
+            sys.exit(2)
+        env = capture_env([str(v) for v in cred_vars])
+        try:
+            env_file = write_env_file(sid, env, target.run_as, target.become_method, target.become_flags)
+        except (RuntimeError, ValueError) as exc:
+            _emit({"error": f"could not write credential env file: {exc}"})
+            sys.exit(1)
+
+    entry = ScheduleEntry(
+        id=sid,
+        when=when,
+        runnable=runnable,
+        args=args,
+        enabled=bool(spec.enabled.value),
+        run_as=target.run_as,
+        become_method=target.become_method,
+        env_file=env_file,
+    )
+    upsert_schedule(path, entry)
+    _emit({"ok": True, "id": sid, "runnable": runnable, "run_as": target.run_as, "env_file": bool(env_file)})
+
+
+def _cmd_remove(spec: rs.RunSpec) -> None:
+    path = _cfg_path(spec)
+    sid = str(spec.id.value)
+    existing = next((e for e in load_schedules(path) if e.id == sid), None)
+    removed = remove_schedule(path, sid)
+    if existing and existing.env_file:
+        remove_env_file(existing.env_file, existing.run_as, existing.become_method)
+    _emit({"ok": removed, "id": sid})
+
+
+def _cmd_list(spec: rs.RunSpec) -> None:
+    path = _cfg_path(spec)
+    out = []
+    for entry in load_schedules(path):
+        record = entry.to_dict()
+        nxt = next_fire_time(entry.when) if entry.enabled else None
+        record["next_run"] = nxt.isoformat() if nxt else None
+        out.append(record)
+    _emit({"schedules": out, "venv": venv_name(), "config": str(path)})
+
+
+def _cmd_run_now(spec: rs.RunSpec) -> None:
+    path = _cfg_path(spec)
+    sid = str(spec.id.value)
+    entry = next((e for e in load_schedules(path) if e.id == sid), None)
+    if entry is None:
+        _emit({"error": f"no schedule with id '{sid}'"})
+        sys.exit(2)
+    target = resolve_target(entry.runnable)
+    if target is None:
+        _emit({"error": f"runnable '{entry.runnable}' not found in this venv"})
+        sys.exit(2)
+    result = run_runnable(
+        target.binary,
+        [],
+        dict(entry.args),
+        source_toml=target.source,
+        run_as=entry.run_as or target.run_as,
+        become_method=entry.become_method or target.become_method,
+        become_flags=target.become_flags,
+        env_file=entry.env_file,
+    )
+    _emit(
+        {
+            "id": sid,
+            "runnable": entry.runnable,
+            "exit_code": result.returncode,
+            "stdout": (result.stdout or "").strip(),
+            "stderr": (result.stderr or "").strip(),
+        }
+    )
+    sys.exit(0 if result.returncode == 0 else 1)
+
+
+def _cmd_install_service(spec: rs.RunSpec) -> None:
+    from .service import install_service
+
+    result = install_service(enable=bool(spec.enable.value))
+    _emit(result)
+
+
+def main() -> None:
+    spec = rs.parse("runspec-scheduler")
+    command = spec.runspec_command
+    if command == "run":
+        _cmd_run(spec)
+    elif command == "add":
+        _cmd_add(spec)
+    elif command == "remove":
+        _cmd_remove(spec)
+    elif command == "list":
+        _cmd_list(spec)
+    elif command == "run-now":
+        _cmd_run_now(spec)
+    elif command == "install-service":
+        _cmd_install_service(spec)
+    else:  # pragma: no cover - require-command makes this unreachable
+        _emit({"error": "no command — try: run, add, remove, list, run-now, install-service"})
+        sys.exit(2)