runon 0.1.0__py3-none-any.whl

runon/__init__.py

@@ -0,0 +1,35 @@
+"""runon — run shell programs locally, on one host, or across a group."""
+
+__version__ = "0.1.0"
+
+from .errors import (
+    ConfigError,
+    ProgramInvalid,
+    RunonError,
+    UnknownGroup,
+    UnknownHost,
+    UnknownProgram,
+)
+from .inventory import Group, Host, Inventory
+from .program import Program, Workspace
+from .transport import FakeTransport, LocalTransport, Result, SSHTransport, Transport
+
+__all__ = [
+    "ConfigError",
+    "FakeTransport",
+    "Group",
+    "Host",
+    "Inventory",
+    "LocalTransport",
+    "Program",
+    "ProgramInvalid",
+    "Result",
+    "RunonError",
+    "SSHTransport",
+    "Transport",
+    "UnknownGroup",
+    "UnknownHost",
+    "UnknownProgram",
+    "Workspace",
+    "__version__",
+]

runon/cli.py

@@ -0,0 +1,267 @@
+"""The command surface.
+
+Three scopes — local, host, group — sharing the same verbs, because where the
+work happens and what the work is are separate questions and the CLI should not
+tangle them.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__, inventory, runner
+from . import program as program_mod
+from .errors import RunonError
+from .picker import choose
+from .program import Workspace
+from .report import emit
+from .transport import LocalTransport, Result, SSHTransport
+
+REMOTE_VERBS = ("copy", "copy-program", "run-program", "copy-run-program")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="runon",
+        description="Run shell programs on your machine, one server, or a named group.",
+    )
+    parser.add_argument("--version", action="version", version=f"runon {__version__}")
+    parser.add_argument(
+        "-C", "--directory", type=Path, help="workspace to use (default: search up)"
+    )
+    parser.add_argument("--inventory", type=Path, help="inventory file (default: search up)")
+    sub = parser.add_subparsers(dest="scope", required=True)
+
+    # -- local ---------------------------------------------------------------
+    local = sub.add_parser("local", help="run on this machine")
+    local_sub = local.add_subparsers(dest="verb", required=True)
+    run_local = local_sub.add_parser("run-program", help="run a program here")
+    _add_program_args(run_local)
+    layout = local_sub.add_parser("run-layout", help="open a predefined terminal layout")
+    layout.add_argument("--layout", "-l", help="layout name (prompts if omitted)")
+
+    # -- host ----------------------------------------------------------------
+    host = sub.add_parser("host", help="run on one machine")
+    host.add_argument("--host", "-H", required=True, help="inventory name, or user@address")
+    _add_remote_verbs(host)
+
+    # -- group ---------------------------------------------------------------
+    group = sub.add_parser("group", help="run on every machine in a group")
+    group.add_argument("--group", "-g", required=True, help="group name from the inventory")
+    group.add_argument("--parallel", "-j", type=int, default=1, help="hosts at once (default 1)")
+    _add_remote_verbs(group)
+
+    # -- list / init / new ---------------------------------------------------
+    listing = sub.add_parser("list", help="show what is available")
+    listing.add_argument(
+        "what", choices=["programs", "hosts", "groups", "layouts"], nargs="?", default="programs"
+    )
+    init = sub.add_parser("init", help="scaffold a workspace here")
+    init.add_argument("--force", action="store_true", help="write into a non-empty directory")
+    new = sub.add_parser("new-program", help="create a program from the template")
+    new.add_argument("name")
+
+    return parser
+
+
+def _add_program_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--program", "-p", help="program name (prompts if omitted)")
+    parser.add_argument("--verbose", "-v", action="store_true", help="show output from successes")
+    parser.add_argument("--dry-run", action="store_true", help="print what would happen")
+    parser.add_argument("args", nargs="*", help="arguments passed through to main.sh")
+
+
+def _add_remote_verbs(parser: argparse.ArgumentParser) -> None:
+    verbs = parser.add_subparsers(dest="verb", required=True)
+    for verb in REMOTE_VERBS:
+        sub = verbs.add_parser(verb, help=_verb_help(verb))
+        if verb == "copy":
+            sub.add_argument("--local-dir", type=Path, required=True)
+            sub.add_argument("--remote-dir", required=True)
+            sub.add_argument("--verbose", "-v", action="store_true")
+            sub.add_argument("--dry-run", action="store_true")
+        else:
+            _add_program_args(sub)
+
+
+def _verb_help(verb: str) -> str:
+    return {
+        "copy": "copy a local file or directory to the target(s)",
+        "copy-program": "copy a program (and the functions library) to the target(s)",
+        "run-program": "run an already-copied program on the target(s)",
+        "copy-run-program": "copy and run in one step",
+    }[verb]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return _dispatch(args)
+    except RunonError as exc:
+        # Expected failures print what went wrong, not where in our code it did.
+        print(f"runon: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print("\ninterrupted", file=sys.stderr)
+        return 130
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    start = args.directory or Path.cwd()
+    workspace = program_mod.find_workspace(start) or Workspace(root=start)
+    inv = inventory.load(args.inventory, start=start)
+
+    if args.scope == "init":
+        return _init(start, force=args.force)
+    if args.scope == "new-program":
+        return _new_program(workspace, args.name)
+    if args.scope == "list":
+        return _list(workspace, inv, args.what)
+    if args.scope == "local":
+        return _local(workspace, args)
+    return _remote(workspace, inv, args)
+
+
+def _resolve_program(workspace: Workspace, name: str | None):
+    # An explicitly empty --program is almost always an unset shell variable.
+    # Falling through to the picker would make a scripted run do nothing and
+    # still report success, so it is refused instead.
+    if name is not None and not name.strip():
+        raise RunonError("--program was given an empty value")
+
+    programs = workspace.programs()
+    # Checked before the name is looked up: someone who has not set up a
+    # workspace yet needs to be told that, not told their program is missing
+    # from an empty list.
+    if not programs:
+        raise RunonError(
+            f"no programs found under {workspace.programs_path}\n\n"
+            "Run 'runon init' here to scaffold a workspace, or use -C to point at one."
+        )
+    if name:
+        return workspace.program(program_mod.validate_name(name))
+    return choose(programs)
+
+
+def _local(workspace: Workspace, args) -> int:
+    host = inventory.Host(name="local", address="localhost")
+    transport = LocalTransport()
+
+    if args.verb == "run-layout":
+        layouts = workspace.layouts()
+        if not layouts:
+            raise RunonError(f"no layouts found under {workspace.layouts_path}")
+        if args.layout:
+            chosen = next((lay for lay in layouts if lay.name == args.layout), None)
+            if chosen is None:
+                raise RunonError(f"no layout named {args.layout!r}")
+        else:
+            chosen = choose(layouts)
+        if chosen is None:
+            return 0
+        script = workspace.layouts_path / f"{chosen.name}.sh"
+        result = transport.run(host, f"sh {script}")
+        return emit([result], verbose=True)
+
+    program = _resolve_program(workspace, args.program)
+    if program is None:
+        return 0
+    if args.dry_run:
+        print(f"would run {program.name} on the local machine")
+        return 0
+    result = runner.run_program(transport, host, workspace, program, args=args.args, remote=False)
+    return emit([result], verbose=args.verbose)
+
+
+def _remote(workspace: Workspace, inv: inventory.Inventory, args) -> int:
+    if args.scope == "host":
+        hosts = [inv.host(args.host)]
+        parallel = 1
+    else:
+        hosts = inv.group(args.group)
+        parallel = max(1, args.parallel)
+    if not hosts:
+        raise RunonError("no hosts selected")
+
+    transport = SSHTransport()
+
+    if args.verb == "copy":
+        if args.dry_run:
+            _print_plan(hosts, f"copy {args.local_dir} -> {args.remote_dir}")
+            return 0
+        results = runner.fan_out(
+            hosts, lambda h: transport.copy(h, args.local_dir, args.remote_dir), parallel=parallel
+        )
+        return emit(results, verbose=args.verbose)
+
+    program = _resolve_program(workspace, args.program)
+    if program is None:
+        return 0
+    if args.dry_run:
+        _print_plan(hosts, f"{args.verb} {program.name}")
+        return 0
+
+    def work(host) -> Result | list[Result]:
+        if args.verb == "copy-program":
+            return runner.copy_program(transport, host, workspace, program)
+        if args.verb == "run-program":
+            return runner.run_program(transport, host, workspace, program, args=args.args)
+        copied = runner.copy_program(transport, host, workspace, program)
+        failed = [r for r in copied if not r.ok]
+        if failed:
+            return failed[0]
+        return runner.run_program(transport, host, workspace, program, args=args.args)
+
+    results = runner.fan_out(hosts, work, parallel=parallel)
+    return emit(results, verbose=args.verbose)
+
+
+def _print_plan(hosts, action: str) -> None:
+    print(f"would {action} on:")
+    for host in hosts:
+        print(f"  {host.name}  ({host.ssh_target})")
+
+
+def _list(workspace: Workspace, inv: inventory.Inventory, what: str) -> int:
+    if what == "programs":
+        items = workspace.programs()
+        if not items:
+            print(f"no programs under {workspace.programs_path}")
+            print("Run 'runon init' here to scaffold a workspace.")
+            return 0
+        width = max(len(p.name) for p in items)
+        for p in items:
+            print(f"  {p.name:<{width}}  {p.description}".rstrip())
+    elif what == "layouts":
+        for lay in workspace.layouts():
+            print(f"  {lay.name}")
+    elif what == "hosts":
+        for name, host in sorted(inv.hosts.items()):
+            print(f"  {name:<20} {host.ssh_target}")
+    else:
+        for name, grp in sorted(inv.groups.items()):
+            print(f"  {name:<20} {', '.join(grp.hosts)}")
+    return 0
+
+
+def _init(root: Path, *, force: bool) -> int:
+    from .scaffold import write_workspace
+
+    created = write_workspace(root, force=force)
+    for path in created:
+        print(f"  created {path.relative_to(root)}")
+    print("\nTry:  runon list programs")
+    print("      runon local run-program --program hello-world")
+    return 0
+
+
+def _new_program(workspace: Workspace, name: str) -> int:
+    from .scaffold import write_program
+
+    program_mod.validate_name(name)
+    path = write_program(workspace.programs_path, name)
+    print(f"  created {path}")
+    return 0

runon/errors.py

@@ -0,0 +1,33 @@
+"""Errors a user can act on.
+
+Every one of these is printed without a traceback, because a stack trace tells
+an operator nothing they can use about a typo'd host name.
+"""
+
+
+class RunonError(Exception):
+    """Base for anything we expect and can explain."""
+
+
+class ConfigError(RunonError):
+    pass
+
+
+class UnknownHost(RunonError):
+    pass
+
+
+class UnknownGroup(RunonError):
+    pass
+
+
+class UnknownProgram(RunonError):
+    pass
+
+
+class ProgramInvalid(RunonError):
+    pass
+
+
+class RemoteFailure(RunonError):
+    pass

runon/inventory.py

@@ -0,0 +1,142 @@
+"""Who the hosts are, and which groups they belong to.
+
+One TOML file rather than a directory tree of JSON: an operator should be able
+to read the whole inventory in one screen and diff it in a review.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .errors import ConfigError, UnknownGroup, UnknownHost
+
+DEFAULT_FILENAME = "inventory.toml"
+
+
+@dataclass(frozen=True)
+class Host:
+    """A machine runon can reach.
+
+    ``address`` is handed to ssh untouched, so anything ssh understands works:
+    a bare hostname, user@host, or a Host alias out of ~/.ssh/config.
+    """
+
+    name: str
+    address: str
+    port: int | None = None
+    user: str | None = None
+    #: Free-form, exported to programs as RUNON_VAR_<KEY>.
+    vars: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def ssh_target(self) -> str:
+        return f"{self.user}@{self.address}" if self.user else self.address
+
+
+@dataclass(frozen=True)
+class Group:
+    name: str
+    hosts: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Inventory:
+    hosts: dict[str, Host]
+    groups: dict[str, Group]
+    source: Path | None = None
+
+    def host(self, name: str) -> Host:
+        """Resolves a name, falling back to treating it as a literal address.
+
+        This is what collapses the original tool's separate "named instance" and
+        "ad-hoc target" commands into one: `--host web-1` uses the inventory,
+        `--host root@10.0.0.4` just works, and neither needs its own verb.
+        """
+        if name in self.hosts:
+            return self.hosts[name]
+        if _looks_like_address(name):
+            return Host(name=name, address=name)
+        raise UnknownHost(
+            f"no host named {name!r} in the inventory, and it does not look like an address.\n"
+            f"Known hosts: {', '.join(sorted(self.hosts)) or '(none)'}"
+        )
+
+    def group(self, name: str) -> list[Host]:
+        if name not in self.groups:
+            raise UnknownGroup(
+                f"no group named {name!r}.\n"
+                f"Known groups: {', '.join(sorted(self.groups)) or '(none)'}"
+            )
+        return [self.host(h) for h in self.groups[name].hosts]
+
+
+def _looks_like_address(value: str) -> bool:
+    """True for things ssh would accept but an inventory lookup missed."""
+    return "@" in value or "." in value or value == "localhost"
+
+
+def load(path: Path | None = None, *, start: Path | None = None) -> Inventory:
+    """Reads an inventory, or returns an empty one when there is no file.
+
+    An absent inventory is not an error: running programs on the local machine
+    needs no hosts at all, and requiring a config file to do that would be
+    friction for no reason.
+    """
+    if path is None:
+        path = find(start or Path.cwd())
+    if path is None:
+        return Inventory(hosts={}, groups={})
+    if not path.is_file():
+        raise ConfigError(f"inventory file not found: {path}")
+
+    try:
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{path} is not valid TOML: {exc}") from exc
+
+    return _parse(raw, path)
+
+
+def find(start: Path) -> Path | None:
+    """Walks up from `start` looking for an inventory, like git finds .git."""
+    for directory in [start, *start.parents]:
+        candidate = directory / DEFAULT_FILENAME
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _parse(raw: dict, source: Path) -> Inventory:
+    hosts: dict[str, Host] = {}
+    for name, spec in (raw.get("hosts") or {}).items():
+        if not isinstance(spec, dict):
+            raise ConfigError(f"{source}: host {name!r} must be a table")
+        address = spec.get("address", name)
+        port = spec.get("port")
+        if port is not None and not isinstance(port, int):
+            raise ConfigError(f"{source}: host {name!r} has a non-integer port")
+        hosts[name] = Host(
+            name=name,
+            address=str(address),
+            port=port,
+            user=spec.get("user"),
+            vars={str(k): str(v) for k, v in (spec.get("vars") or {}).items()},
+        )
+
+    groups: dict[str, Group] = {}
+    for name, spec in (raw.get("groups") or {}).items():
+        members = spec.get("hosts") if isinstance(spec, dict) else spec
+        if not isinstance(members, list) or not all(isinstance(m, str) for m in members):
+            raise ConfigError(f"{source}: group {name!r} must list host names")
+        # Catching this here means a typo in a group fails before runon has
+        # half-finished a rollout across the hosts it could resolve.
+        unknown = [m for m in members if m not in hosts and not _looks_like_address(m)]
+        if unknown:
+            raise ConfigError(
+                f"{source}: group {name!r} refers to unknown hosts: {', '.join(unknown)}"
+            )
+        groups[name] = Group(name=name, hosts=tuple(members))
+
+    return Inventory(hosts=hosts, groups=groups, source=source)

runon/picker.py

@@ -0,0 +1,39 @@
+"""Choosing a program when you did not name one."""
+
+from __future__ import annotations
+
+import sys
+
+from .program import Program
+
+
+def choose(programs: list[Program], *, stream=None, prompt_stream=None) -> Program | None:
+    """Numbered menu on stderr, so stdout stays pipeable.
+
+    Returns None if the user aborts, which the caller treats as a clean exit
+    rather than an error — changing your mind is not a failure.
+    """
+    stream = stream or sys.stdin
+    out = prompt_stream or sys.stderr
+
+    if not programs:
+        return None
+    if len(programs) == 1:
+        return programs[0]
+
+    for index, program in enumerate(programs, 1):
+        suffix = f"  — {program.description}" if program.description else ""
+        print(f"  {index:>2}. {program.name}{suffix}", file=out)
+    print("", file=out)
+
+    while True:
+        print(f"Select 1-{len(programs)} (or blank to cancel): ", end="", file=out, flush=True)
+        raw = stream.readline()
+        if not raw:
+            return None
+        raw = raw.strip()
+        if raw == "":
+            return None
+        if raw.isdigit() and 1 <= int(raw) <= len(programs):
+            return programs[int(raw) - 1]
+        print(f"  not a choice: {raw!r}", file=out)

runon/program.py

@@ -0,0 +1,127 @@
+"""Programs and functions: the unit of work, and the reason the tool is small.
+
+A program is a directory with a ``main.sh``. Adding a capability means adding a
+directory — the tool itself never changes. That is the whole design: the CLI
+knows how to *reach* machines, and shell knows what to *do* on them, and neither
+has to learn the other's job.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import ProgramInvalid, UnknownProgram
+
+ENTRY_POINT = "main.sh"
+PROGRAMS_DIR = "programs"
+FUNCTIONS_DIR = "functions"
+LAYOUTS_DIR = "layouts"
+
+_NAME = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._-]*$")
+
+
+@dataclass(frozen=True)
+class Program:
+    name: str
+    path: Path
+
+    @property
+    def entry_point(self) -> Path:
+        return self.path / ENTRY_POINT
+
+    @property
+    def description(self) -> str:
+        """The first ``# comment`` line of main.sh, if there is one.
+
+        Cheap convention, no metadata file: a program that describes itself in a
+        comment is a program whose description cannot drift out of date.
+        """
+        try:
+            for line in self.entry_point.read_text(encoding="utf-8").splitlines()[:10]:
+                stripped = line.strip()
+                if stripped.startswith("#!"):
+                    continue
+                if stripped.startswith("#"):
+                    text = stripped.lstrip("#").strip()
+                    if text:
+                        return text
+                elif stripped:
+                    break
+        except OSError:
+            pass
+        return ""
+
+
+@dataclass(frozen=True)
+class Workspace:
+    """The directory holding programs/, functions/ and layouts/."""
+
+    root: Path
+
+    @property
+    def programs_path(self) -> Path:
+        return self.root / PROGRAMS_DIR
+
+    @property
+    def functions_path(self) -> Path:
+        return self.root / FUNCTIONS_DIR
+
+    @property
+    def layouts_path(self) -> Path:
+        return self.root / LAYOUTS_DIR
+
+    def programs(self) -> list[Program]:
+        if not self.programs_path.is_dir():
+            return []
+        found = [
+            Program(name=child.name, path=child)
+            for child in sorted(self.programs_path.iterdir())
+            if child.is_dir() and (child / ENTRY_POINT).is_file()
+        ]
+        return found
+
+    def program(self, name: str) -> Program:
+        for program in self.programs():
+            if program.name == name:
+                return program
+        available = ", ".join(p.name for p in self.programs()) or "(none)"
+        raise UnknownProgram(f"no program named {name!r}.\nAvailable: {available}")
+
+    def functions(self) -> list[Path]:
+        if not self.functions_path.is_dir():
+            return []
+        return sorted(p for p in self.functions_path.iterdir() if p.suffix == ".sh")
+
+    def layouts(self) -> list[Program]:
+        """Layouts are programs too — a layout is just a script that opens panes."""
+        if not self.layouts_path.is_dir():
+            return []
+        return [
+            Program(name=child.stem, path=self.layouts_path)
+            for child in sorted(self.layouts_path.iterdir())
+            if child.suffix == ".sh"
+        ]
+
+
+def find_workspace(start: Path) -> Workspace | None:
+    """Walks up looking for a directory containing programs/."""
+    for directory in [start, *start.parents]:
+        if (directory / PROGRAMS_DIR).is_dir():
+            return Workspace(root=directory)
+    return None
+
+
+def validate_name(name: str) -> str:
+    """Program names become path components and shell arguments.
+
+    Rejecting the awkward ones here means nothing downstream has to quote
+    defensively, and `--program ../../etc` is refused rather than resolved.
+    """
+    if not _NAME.match(name):
+        raise ProgramInvalid(
+            f"{name!r} is not a valid program name. "
+            "Use letters, digits, dot, dash or underscore, starting with a letter or digit."
+        )
+    return name

runon/report.py

@@ -0,0 +1,42 @@
+"""Printing results in a way an operator can scan."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterable
+
+from .transport import Result
+
+
+def emit(results: Iterable[Result], *, verbose: bool = False, stream=None) -> int:
+    """Prints one line per host and returns the exit code for the whole run.
+
+    Non-zero if any host failed, because a rollout that worked on nine of ten
+    machines has not worked.
+    """
+    stream = stream or sys.stdout
+    results = list(results)
+    failures = 0
+
+    for result in results:
+        status = "ok" if result.ok else f"FAILED ({result.exit_code})"
+        print(f"{result.host:<24} {status}", file=stream)
+        if result.ok and verbose and result.stdout.strip():
+            _indent(result.stdout, stream)
+        if not result.ok:
+            failures += 1
+            # Always show why a failure failed. Needing a flag to see the error
+            # means running it twice.
+            if result.stderr.strip():
+                _indent(result.stderr, stream)
+            elif result.stdout.strip():
+                _indent(result.stdout, stream)
+
+    if len(results) > 1:
+        print(f"\n{len(results) - failures}/{len(results)} ok", file=stream)
+    return 1 if failures else 0
+
+
+def _indent(text: str, stream) -> None:
+    for line in text.rstrip().splitlines():
+        print(f"    {line}", file=stream)