penrun 0.1.0__tar.gz

penrun-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.3
+Name: penrun
+Version: 0.1.0
+Summary: Run any command inside a well-defined, timestamped artifacts directory.
+Author: AISEC Pentesting Team
+License: Apache-2.0
+Requires-Python: >=3.14

penrun-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: CC0-1.0
+
+[build-system]
+requires = ["uv_build>=0.9.11,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "penrun"
+version = "0.1.0"
+description = "Run any command inside a well-defined, timestamped artifacts directory."
+requires-python = ">=3.14"
+license = { text = "Apache-2.0" }
+authors = [{ name = "AISEC Pentesting Team" }]
+
+[project.scripts]
+penrun = "penrun.cli:main"
+
+[dependency-groups]
+dev = [
+    "ruff",
+    "mypy",
+    "ty",
+    "reuse>=6.2.0",
+    "rust-just>=1.38.0",
+]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 110
+
+[tool.ruff.lint]
+select = [
+    "B",    # flake8-bugbear
+    "A",    # flake8-builtins
+    "ASYNC",# flake8-async
+    "C4",   # flake8-comprehensions
+    "E",    # pycodestlye
+    "F",    # pyflakes
+    "FA",   # flake8-future-annotations
+    "FLY",  # flynt
+    "FURB", # refurb
+    "I",    # isort
+    "IC",   # flake8-import-conventions
+    "LOG",  # flake8-logging
+    "PGH",  # pygrep-hooks
+    "PIE",  # flake8-pie
+    "PL",   # pylint
+    "PTH",  # flake8-use-pathlib
+    "Q",    # flake8-quotes
+    "RSE",  # flake8-raise
+    "RUF100",  # unused-noqa
+    "TD",   # flake8-todos
+    "TID",  # flake8-tidy-imports
+    "UP",   # pyupgrade
+]
+
+[tool.mypy]
+strict = true
+native_parser = true
+num_workers = 4

penrun-0.1.0/src/penrun/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from api import run, run_batched
+
+__all__ = [
+    "run",
+    "run_batched",
+]

penrun-0.1.0/src/penrun/__main__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import sys
+
+from penrun.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

penrun-0.1.0/src/penrun/api.py

@@ -0,0 +1,84 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from contextlib import nullcontext
+from dataclasses import dataclass
+from pathlib import Path
+
+from penrun.batch import BatchOptions, BatchRunner, InputItem
+from penrun.config import Config
+from penrun.locking import FileLock
+from penrun.runner import Runner, RunRequest
+
+__all__ = ["BatchOptions", "InputItem", "InvocationData", "RunOptions", "run", "run_batched"]
+
+
+@dataclass(frozen=True, slots=True)
+class RunOptions:
+    config: Config | None = None
+    tag: str = ""
+    artifactsdir_override: Path | None = None
+    base_override: Path | None = None
+    chdir: bool = False
+    include_env: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class InvocationData:
+    # The batch's shared executable and args. Never executed directly -
+    # each job's own InputItem.values is already the complete, resolved
+    # command - but arg0/arg0_name give every job in the batch the same
+    # {scriptname} artifacts_template placeholder, and argv is available
+    # for callers that want to log/display the batch's base invocation.
+    # Turning raw stdin lines/a -T template into this shape is a CLI-only
+    # concern - see cli.py.
+    arg0: str
+    arg0_name: str | None
+    argv: list[str]
+    inputs: list[InputItem]
+
+
+def _lock(config: Config) -> nullcontext[None] | FileLock:
+    return FileLock(Path(config.lock)) if config.lock else nullcontext()
+
+
+def run(cmd: list[str], options: RunOptions | None = None, *, mirror_to_stdout: bool = True) -> int:
+    options = options or RunOptions()
+    config = options.config or Config()
+    request = RunRequest(
+        cmd=cmd,
+        tag=options.tag,
+        artifactsdir_override=options.artifactsdir_override,
+        base_override=options.base_override,
+        chdir=options.chdir,
+        include_env=options.include_env,
+        mirror_to_stdout=mirror_to_stdout,
+    )
+    with _lock(config):
+        return Runner(config).run(request)
+
+
+def run_batched(
+    data: InvocationData,
+    options: RunOptions | None = None,
+    *,
+    named_jobs: bool = False,
+    batch: BatchOptions | None = None,
+) -> int:
+    options = options or RunOptions()
+    batch = batch or BatchOptions()
+    config = options.config or Config()
+    scriptname = data.arg0_name if data.arg0_name is not None else Path(data.arg0).stem
+    base_request = RunRequest(
+        cmd=[],
+        tag=options.tag,
+        artifactsdir_override=options.artifactsdir_override,
+        base_override=options.base_override,
+        chdir=options.chdir,
+        include_env=options.include_env,
+        scriptname=scriptname,
+        named_jobs=named_jobs,
+    )
+    with _lock(config):
+        return BatchRunner(Runner(config), batch, base_request).run(data.inputs)

penrun-0.1.0/src/penrun/artifacts.py

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from penrun.exceptions import ConfigError
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactsPlaceholders:
+    base: str
+    scriptname: str
+    tag: str
+    fragment: str
+    jobname: str
+    timestamp: str
+
+    @property
+    def tagsuffix(self) -> str:
+        return f"-{self.tag}" if self.tag else ""
+
+    def as_dict(self) -> dict[str, str]:
+        return {
+            "base": self.base,
+            "scriptname": self.scriptname,
+            "tag": self.tag,
+            "tagsuffix": self.tagsuffix,
+            "fragment": self.fragment,
+            "jobname": self.jobname,
+            "timestamp": self.timestamp,
+        }
+
+
+def render_artifactsdir(template: str, placeholders: ArtifactsPlaceholders) -> Path:
+    try:
+        rendered = template.format(**placeholders.as_dict())
+    except KeyError as e:
+        raise ConfigError(f"invalid artifacts_template placeholder: {e}") from e
+    return Path(rendered)
+
+
+def timestamp_now() -> str:
+    return datetime.now().strftime("%Y%m%d-%H%M%S.%f")
+
+
+def now_iso() -> str:
+    return datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def update_latest_symlink(link_path: Path, target: Path) -> None:
+    link_path.parent.mkdir(parents=True, exist_ok=True)
+    if link_path.is_symlink() or link_path.exists():
+        link_path.unlink()
+    link_path.symlink_to(os.path.relpath(target, link_path.parent))
+
+
+class ArtifactsDir:
+    def __init__(self, path: Path, latest_dir: Path) -> None:
+        self.path = path
+        self._latest_dir = latest_dir
+
+    def create(self) -> None:
+        self.path.mkdir(parents=True, exist_ok=True)
+
+    def output_path(self) -> Path:
+        return self.path.joinpath("OUTPUT.zst")
+
+    def update_latest_symlink(self) -> None:
+        update_latest_symlink(self._latest_dir.joinpath("LATEST"), self.path)
+
+    def write_meta(
+        self,
+        *,
+        command: list[str],
+        start_time: str,
+        end_time: str,
+        exit_code: int,
+        env: dict[str, str] | None = None,
+    ) -> None:
+        meta = {
+            "command": command,
+            "start_time": start_time,
+            "end_time": end_time,
+            "exit_code": exit_code,
+        }
+        if env is not None:
+            meta["env"] = env
+        self.path.joinpath("META.json").write_text(json.dumps(meta) + "\n")

penrun-0.1.0/src/penrun/batch.py

@@ -0,0 +1,160 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import shlex
+import threading
+import time
+from collections.abc import Iterable
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, replace
+
+from penrun.artifacts import timestamp_now
+from penrun.constants import EXIT_CODE_FAILED_FIRST, EXIT_CODE_JOB_FAILED
+from penrun.output import log
+from penrun.runner import Runner, RunRequest
+
+
+def _ratio(count: int, total: int) -> str:
+    pct = count / total * 100 if total else 0.0
+    return f"{count}/{total} ({pct:.0f}%)"
+
+
+def _format_duration(seconds: float) -> str:
+    seconds = int(seconds)
+    hours, seconds = divmod(seconds, 3600)
+    minutes, seconds = divmod(seconds, 60)
+    if hours:
+        return f"{hours}:{minutes:02d}:{seconds:02d}"
+    return f"{minutes}:{seconds:02d}"
+
+
+@dataclass(frozen=True, slots=True)
+class InputItem:
+    # A single batch job's fully-resolved command (values[0] is the
+    # executable) plus the artifacts directory name it should run under.
+    # Building these from raw input lines/templates is a CLI-only concern -
+    # see cli.py.
+    values: list[str]
+    dirname: str
+
+
+@dataclass(frozen=True, slots=True)
+class BatchOptions:
+    jobs: int = 1
+    sleep: float = 0.0
+    until: bool = False
+
+
+class BatchRunner:
+    def __init__(self, runner: Runner, options: BatchOptions, base_request: RunRequest) -> None:
+        self._runner = runner
+        self._options = options
+        self._base_request = base_request
+
+    def run(self, items: Iterable[InputItem]) -> int:
+        # All jobs of one batch share a single timestamp, so they land
+        # together under one DEFAULT_BATCH_TEMPLATE run-{timestamp} dir
+        # instead of each picking their own.
+        items = list(items)
+        self._base_request = replace(self._base_request, batch=True, timestamp=timestamp_now())
+        self._update_latest(items)
+
+        if self._options.jobs > 1:
+            return self._run_parallel(items)
+        return self._run_sequential(items)
+
+    def _update_latest(self, items: list[InputItem]) -> None:
+        # Point a single top-level LATEST at the run-{timestamp} directory
+        # shared by every job of this batch, rather than each job trying
+        # to maintain its own (see Runner.update_batch_latest).
+        if items:
+            self._runner.update_batch_latest(self._build_request(items[0]))
+
+    def _build_request(self, item: InputItem, *, mirror_to_stdout: bool = True) -> RunRequest:
+        return replace(
+            self._base_request,
+            cmd=item.values,
+            jobname=item.dirname,
+            mirror_to_stdout=mirror_to_stdout,
+        )
+
+    def _run_sequential(self, items: Iterable[InputItem]) -> int:
+        result = 0
+        for item in items:
+            log(f"Starting command '{shlex.join(item.values)}'.")
+            ret = self._runner.run(self._build_request(item))
+            if ret != 0:
+                if self._options.until:
+                    return EXIT_CODE_FAILED_FIRST
+                result = EXIT_CODE_JOB_FAILED
+            time.sleep(self._options.sleep)
+        return result
+
+    def _run_parallel(self, items: list[InputItem]) -> int:
+        # Live terminal output is disabled for job control: interleaved
+        # output from parallel jobs is unreadable anyway - only the
+        # compressed OUTPUT file is kept per job.
+        total = len(items)
+        start = time.monotonic()
+        stop = threading.Event()
+        lock = threading.Lock()
+        active = 0
+        finished = 0
+        executed = 0
+        succeeded = 0
+
+        def progress(prefix: str) -> None:
+            remaining = total - active - finished
+            elapsed = time.monotonic() - start
+            eta = _format_duration(elapsed / finished * remaining) if finished else "unknown"
+            success_rate = _ratio(succeeded, executed) if executed else "n/a"
+            log(
+                f"{prefix} Active: {_ratio(active, total)}, "
+                f"finished: {_ratio(finished, total)}, "
+                f"remaining: {_ratio(remaining, total)}. "
+                f"Runtime: {_format_duration(elapsed)}, ETA: {eta}. "
+                f"Success rate: {success_rate}."
+            )
+
+        def job(item: InputItem) -> int | None:
+            nonlocal active, finished, executed, succeeded
+            if stop.is_set():
+                with lock:
+                    finished += 1
+                return None
+
+            with lock:
+                active += 1
+                progress(f"Scheduling job '{shlex.join(item.values)}'.")
+
+            ret = self._runner.run(self._build_request(item, mirror_to_stdout=False))
+
+            with lock:
+                active -= 1
+                finished += 1
+                executed += 1
+                if ret == 0:
+                    succeeded += 1
+                progress("Job terminated.")
+            return ret
+
+        failed = False
+        with ThreadPoolExecutor(max_workers=self._options.jobs) as executor:
+            futures = []
+            for item in items:
+                if stop.is_set():
+                    break
+                futures.append(executor.submit(job, item))
+                time.sleep(self._options.sleep)
+
+            for future in futures:
+                ret = future.result()
+                if ret is not None and ret != 0:
+                    failed = True
+                    if self._options.until:
+                        stop.set()
+
+        if failed:
+            return EXIT_CODE_FAILED_FIRST if self._options.until else EXIT_CODE_JOB_FAILED
+        return 0

penrun-0.1.0/src/penrun/cli.py

@@ -0,0 +1,242 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import argparse
+import os
+import shlex
+import signal
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from penrun import api
+from penrun import config as config_mod
+from penrun.api import BatchOptions, InputItem, InvocationData, RunOptions
+from penrun.config import Config
+from penrun.exceptions import PenrunError, UsageError
+from penrun.output import log
+
+_SHORT_FLAG_LEN = len("-x")
+
+
+@dataclass(frozen=True, slots=True)
+class _OptionSpec:
+    short: str
+    long: str
+    dest: str
+    takes_value: bool
+    help: str
+    type: type = str
+    default: object = None
+
+
+OPTIONS: tuple[_OptionSpec, ...] = (
+    _OptionSpec(
+        "-S", "--sleep", "sleep", True, "Sleep this time between jobs (batch mode)", type=float, default=0.0
+    ),
+    _OptionSpec(
+        "-T", "--template", "template", True, "A command template; {1} is the input line, may repeat"
+    ),
+    _OptionSpec("-b", "--batch", "batch", False, "Batched mode: read commands from stdin", default=False),
+    _OptionSpec("-B", "--base-dir", "base", True, "Use BASE as the penrun-artifacts base dir"),
+    _OptionSpec("-c", "--config", "config", True, "Use this config file exclusively"),
+    _OptionSpec("-d", "--artifacts-dir", "dir", True, "Use artifactsdir DIR"),
+    _OptionSpec(
+        "-C",
+        "--chdir",
+        "chdir",
+        False,
+        "Run COMMAND with its cwd set to the artifacts dir",
+        default=False,
+    ),
+    _OptionSpec(
+        "-j",
+        "--jobs",
+        "jobs",
+        True,
+        "Process this many jobs at a time (batch mode)",
+        type=int,
+        default=1,
+    ),
+    _OptionSpec(
+        "-N",
+        "--name-by-arg",
+        "name_by_fragment",
+        False,
+        "Batch mode: name each job's directory after its input line/argument instead of the program name",
+        default=False,
+    ),
+    _OptionSpec("-t", "--tag", "tag", True, "Add a tag to this run", default=""),
+    _OptionSpec("-u", "--until", "until", False, "In batch mode: stop after the first error", default=False),
+)
+
+
+# Splits argv into penrun's own option tokens and the trailing COMMAND,
+# stopping at the first token that isn't (part of) one of our own options
+# - like POSIX getopt(3)/bash's `getopts`, so `penrun -t foo ls -la` passes
+# `-la` through to `ls` untouched. argparse alone can't express this (it
+# permutes options and positionals freely), so this pre-scan hands it only
+# the option tokens.
+def _split_argv(argv: list[str]) -> tuple[list[str], list[str]]:
+    value_flags = {opt.short for opt in OPTIONS if opt.takes_value} | {
+        opt.long for opt in OPTIONS if opt.takes_value
+    }
+    bool_flags = (
+        {opt.short for opt in OPTIONS if not opt.takes_value}
+        | {opt.long for opt in OPTIONS if not opt.takes_value}
+        | {"-h", "--help"}
+    )
+
+    i = 0
+    n = len(argv)
+    while i < n:
+        tok = argv[i]
+
+        if tok == "--":
+            return argv[:i], argv[i + 1 :]
+        if tok in bool_flags:
+            i += 1
+            continue
+        if tok in value_flags:
+            i += 2 if i + 1 < n else 1
+            continue
+        if tok.startswith("--") and tok.partition("=")[0] in value_flags:
+            i += 1  # value is attached, e.g. --tag=foo
+            continue
+        if len(tok) > _SHORT_FLAG_LEN and tok[0] == "-" and tok[1] != "-" and tok[:2] in value_flags:
+            i += 1  # value is attached, e.g. -tfoo
+            continue
+
+        break
+
+    return argv[:i], argv[i:]
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Run COMMAND inside a well-defined, timestamped artifacts directory.",
+    )
+    for opt in OPTIONS:
+        if opt.takes_value:
+            parser.add_argument(
+                opt.short,
+                opt.long,
+                dest=opt.dest,
+                type=opt.type,
+                default=opt.default,
+                help=opt.help,
+            )
+        else:
+            parser.add_argument(
+                opt.short,
+                opt.long,
+                dest=opt.dest,
+                action="store_true",
+                default=opt.default,
+                help=opt.help,
+            )
+    return parser
+
+
+def _resolve_config(explicit: str | None) -> Config:
+    if explicit:
+        if explicit != "/dev/null" and not Path(explicit).is_file():
+            raise PenrunError("config does not exist")
+        for key, value in config_mod.find_config_paths().items():
+            os.environ[key] = str(value)
+        if explicit == "/dev/null":
+            return Config()
+        return config_mod.load_config(Path(explicit))
+
+    paths = config_mod.find_config_paths()
+    for key, value in paths.items():
+        os.environ[key] = str(value)
+    chosen = config_mod.select_config_path(paths)
+    return config_mod.load_config(chosen) if chosen else Config()
+
+
+def _sanitize_dirname(name: str) -> str:
+    name = name.strip().replace(os.sep, "_")
+    if os.altsep:
+        name = name.replace(os.altsep, "_")
+    return name if name and name not in {".", ".."} else "job"
+
+
+# The classic -T/{1} template feature: turns one raw stdin line into a full
+# command, either by substituting it into the template (which may repeat
+# {1} anywhere) or, without a template, by treating the line as a command
+# of its own.
+def _build_cmd(template: str | None, fragment: str) -> list[str] | None:
+    cmd_str = template.replace("{1}", fragment) if template else fragment
+    try:
+        cmd = shlex.split(cmd_str)
+    except ValueError as e:
+        log(f"error: invalid command '{cmd_str}': {e}")
+        return None
+    return cmd or None
+
+
+def _read_invocation_data(ns: argparse.Namespace) -> InvocationData:
+    fragments = [line for line in sys.stdin.read().splitlines() if line.strip()]
+
+    inputs: list[InputItem] = []
+    for fragment in fragments:
+        cmd = _build_cmd(ns.template, fragment)
+        if cmd is None:
+            continue
+        dirname = _sanitize_dirname(fragment) if ns.name_by_fragment else Path(cmd[0]).stem
+        inputs.append(InputItem(values=cmd, dirname=dirname))
+
+    if ns.template:
+        arg0, *argv = shlex.split(ns.template)
+    elif inputs:
+        arg0, *argv = inputs[0].values
+    else:
+        arg0, argv = "", []
+
+    return InvocationData(arg0=arg0, arg0_name=None, argv=argv, inputs=inputs)
+
+
+def _run(ns: argparse.Namespace, command: list[str]) -> int:
+    config = _resolve_config(ns.config)
+    options = RunOptions(
+        config=config,
+        tag=ns.tag,
+        artifactsdir_override=Path(ns.dir) if ns.dir else None,
+        base_override=Path(ns.base) if ns.base else None,
+        chdir=ns.chdir,
+    )
+
+    if ns.batch:
+        data = _read_invocation_data(ns)
+        os.environ["PENRUN_BATCH_MODE"] = "1"
+        batch = BatchOptions(jobs=ns.jobs, sleep=ns.sleep, until=ns.until)
+        return api.run_batched(data, options, named_jobs=ns.name_by_fragment, batch=batch)
+
+    if not command:
+        raise UsageError("no command specified")
+
+    return api.run(command, options)
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    own_args, command = _split_argv(argv)
+
+    parser = _build_parser()
+    try:
+        namespace = parser.parse_args(own_args)
+    except SystemExit as e:
+        # argparse handles -h/--help and its own usage errors by printing
+        # and calling sys.exit() directly; translate that into a normal
+        # return so main() never exits the process itself.
+        return int(e.code) if isinstance(e.code, int) else 0
+
+    try:
+        return _run(namespace, command)
+    except PenrunError as e:
+        log(f"error: {e}")
+        return e.exit_code
+    except KeyboardInterrupt:
+        return 128 + signal.SIGINT

penrun-0.1.0/src/penrun/config.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import subprocess
+import tomllib
+import types
+import typing
+from dataclasses import dataclass, fields
+from pathlib import Path
+from typing import Any
+
+from penrun.exceptions import ConfigError
+
+CONFIG_FILENAME = ".penrun.toml"
+USER_CONFIG_PATH = Path("~/.config/penrun/config.toml").expanduser()
+
+ENV_PWD_CONF = "PENRUN_PWD_CONF"
+ENV_GIT_ROOT_CONF = "PENRUN_GIT_ROOT_CONF"
+ENV_USER_CONF = "PENRUN_USER_CONF"
+
+# Precedence order: first match wins, and stops the search.
+_SEARCH_ORDER = (ENV_PWD_CONF, ENV_GIT_ROOT_CONF, ENV_USER_CONF)
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    artifacts_base: str | None = None
+    # None means: use runner.DEFAULT_TEMPLATE, or runner.DEFAULT_BATCH_TEMPLATE
+    # in batch mode - see there.
+    artifacts_template: str | None = None
+    lock: str | None = None
+
+
+def find_config_paths() -> dict[str, Path]:
+    paths: dict[str, Path] = {}
+
+    pwd_conf = Path.cwd().joinpath(CONFIG_FILENAME)
+    if pwd_conf.is_file():
+        paths[ENV_PWD_CONF] = pwd_conf
+
+    git_root_conf = _git_root_config()
+    if git_root_conf is not None:
+        paths[ENV_GIT_ROOT_CONF] = git_root_conf
+
+    if USER_CONFIG_PATH.is_file():
+        paths[ENV_USER_CONF] = USER_CONFIG_PATH
+
+    return paths
+
+
+def select_config_path(paths: dict[str, Path]) -> Path | None:
+    for key in _SEARCH_ORDER:
+        if key in paths:
+            return paths[key]
+    return None
+
+
+def load_config(path: Path) -> Config:
+    with path.open("rb") as f:
+        try:
+            data = tomllib.load(f)
+        except tomllib.TOMLDecodeError as e:
+            raise ConfigError(f"invalid config {path}: {e}") from e
+
+    return _build_config(path, data)
+
+
+def _git_root_config() -> Path | None:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError, FileNotFoundError:
+        return None
+
+    conf = Path(result.stdout.strip()).joinpath(CONFIG_FILENAME)
+    return conf if conf.is_file() else None
+
+
+def _build_config(path: Path, data: dict[str, Any]) -> Config:
+    hints = typing.get_type_hints(Config)
+    allowed = {f.name for f in fields(Config)}
+
+    for key, value in data.items():
+        if key not in allowed:
+            raise ConfigError(f"invalid config {path}: unknown key '{key}'")
+        if not _matches_type(value, hints[key]):
+            raise ConfigError(f"invalid config {path}: '{key}' has the wrong type")
+
+    return Config(**data)
+
+
+def _matches_type(value: Any, tp: Any) -> bool:
+    origin = typing.get_origin(tp)
+
+    # TOML has no null literal, so a present key is always checked against
+    # the non-None member of a `X | None` union.
+    if origin is types.UnionType:
+        return any(_matches_type(value, arg) for arg in typing.get_args(tp) if arg is not type(None))
+    if origin is list:
+        (elem_type,) = typing.get_args(tp) or (Any,)
+        return isinstance(value, list) and all(_matches_type(v, elem_type) for v in value)
+    if tp is str:
+        return isinstance(value, str)
+    return False

penrun-0.1.0/src/penrun/constants.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# EX_USAGE and EX_SOFTWARE follow the BSD sysexits(3) convention:
+# https://www.freebsd.org/cgi/man.cgi?query=sysexits
+
+EXIT_CODE_JOB_FAILED = 1
+EXIT_CODE_FAILED_FIRST = 2
+
+EXIT_CODE_EX_USAGE = 64
+EXIT_CODE_EX_SOFTWARE = 70

penrun-0.1.0/src/penrun/exceptions.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from penrun.constants import EXIT_CODE_EX_SOFTWARE, EXIT_CODE_EX_USAGE
+
+
+class PenrunError(Exception):
+    def __init__(self, message: str, exit_code: int = EXIT_CODE_EX_SOFTWARE) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+class UsageError(PenrunError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, EXIT_CODE_EX_USAGE)
+
+
+class ConfigError(PenrunError):
+    pass
+
+
+class CommandNotFoundError(PenrunError):
+    def __init__(self, command: str) -> None:
+        super().__init__(f"command not found: {command}")
+        self.command = command

penrun-0.1.0/src/penrun/locking.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import fcntl
+import os
+from pathlib import Path
+from types import TracebackType
+
+from penrun.output import log
+
+
+class FileLock:
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._fd: int | None = None
+
+    def __enter__(self) -> FileLock:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.touch(exist_ok=True)
+        self._fd = os.open(self._path, os.O_RDONLY)
+
+        try:
+            fcntl.flock(self._fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            log(f"Could not aquire lock {self._path}")
+            log("Waiting for lock…")
+            fcntl.flock(self._fd, fcntl.LOCK_EX)
+            log("… aquired lock.")
+
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        if self._fd is not None:
+            os.close(self._fd)
+            self._fd = None

penrun-0.1.0/src/penrun/output.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import sys
+
+
+def log(*values: object) -> None:
+    print(*values, file=sys.stderr)

penrun-0.1.0/src/penrun/process.py

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import io
+import subprocess
+import sys
+from compression import zstd
+from dataclasses import dataclass
+from pathlib import Path
+
+from penrun.exceptions import CommandNotFoundError
+
+
+@dataclass(frozen=True, slots=True)
+class PipelineSinks:
+    raw_out_path: Path
+    mirror_to_stdout: bool
+
+
+def run_pipeline(cmd: list[str], env: dict[str, str], sinks: PipelineSinks, cwd: Path | None = None) -> int:
+    with zstd.open(sinks.raw_out_path, mode="wb") as comp_out:
+        try:
+            main_proc = subprocess.Popen(
+                cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, env=env, cwd=cwd
+            )
+        except FileNotFoundError as e:
+            raise CommandNotFoundError(cmd[0]) from e
+
+        return _pump(main_proc, comp_out, mirror_to_stdout=sinks.mirror_to_stdout)
+
+
+def _pump(
+    main_proc: subprocess.Popen[bytes],
+    comp_out: zstd.ZstdFile,
+    *,
+    mirror_to_stdout: bool,
+) -> int:
+    assert main_proc.stdout is not None
+    main_stdout = main_proc.stdout
+
+    try:
+        for chunk in iter(lambda: main_stdout.read(io.DEFAULT_BUFFER_SIZE), b""):
+            comp_out.write(chunk)
+            if mirror_to_stdout:
+                sys.stdout.buffer.write(chunk)
+                sys.stdout.buffer.flush()
+    except BrokenPipeError, KeyboardInterrupt:
+        pass
+    finally:
+        main_stdout.close()
+
+    return main_proc.wait()

penrun-0.1.0/src/penrun/runner.py

@@ -0,0 +1,167 @@
+# SPDX-FileCopyrightText: AISEC Pentesting Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+
+from penrun.artifacts import (
+    ArtifactsDir,
+    ArtifactsPlaceholders,
+    now_iso,
+    render_artifactsdir,
+    timestamp_now,
+    update_latest_symlink,
+)
+from penrun.config import Config
+from penrun.process import PipelineSinks, run_pipeline
+
+DEFAULT_TEMPLATE = "{base}/{scriptname}{tagsuffix}/run-{timestamp}"
+DEFAULT_BATCH_TEMPLATE = "{base}/run-{timestamp}/{jobname}{tagsuffix}"
+# Used instead of DEFAULT_BATCH_TEMPLATE when -N/--name-by-arg is given: jobs
+# are named after their input line, so grouping them under the shared
+# run-{timestamp} dir wouldn't tell different commands' batches apart. This
+# nests run-{timestamp} under a directory named after the command instead,
+# mirroring DEFAULT_TEMPLATE's job/datetime layout.
+DEFAULT_BATCH_TEMPLATE_NAMED = "{base}/{scriptname}{tagsuffix}/run-{timestamp}/{jobname}"
+
+
+def _resolve_executable(cmd: list[str]) -> list[str]:
+    exe = cmd[0]
+    if os.sep in exe or (os.altsep and os.altsep in exe):
+        exe = str(Path(exe).resolve())
+    return [exe, *cmd[1:]]
+
+
+@dataclass(frozen=True, slots=True)
+class RunRequest:
+    cmd: list[str]
+    tag: str = ""
+    artifactsdir_override: Path | None = None
+    base_override: Path | None = None
+    chdir: bool = False
+    # Explicit overrides for the {scriptname}/{jobname} artifacts_template
+    # placeholders. None means: derive from cmd[0] (see _program_name).
+    scriptname: str | None = None
+    jobname: str | None = None
+    mirror_to_stdout: bool = True
+    # Set (along with `timestamp`) by BatchRunner so every job of one
+    # batch shares a single timestamp and picks DEFAULT_BATCH_TEMPLATE.
+    batch: bool = False
+    # Batch mode picked DEFAULT_BATCH_TEMPLATE_NAMED (jobs nested under the
+    # shared scriptname dir) rather than DEFAULT_BATCH_TEMPLATE (jobs named
+    # after the plain scriptname) - see -N/--name-by-arg.
+    named_jobs: bool = False
+    timestamp: str | None = None
+    include_env: bool = False
+
+
+class Runner:
+    def __init__(self, config: Config) -> None:
+        self._config = config
+
+    def run(self, request: RunRequest) -> int:
+        cmd = request.cmd
+
+        artifactsdir, latest_dir = self._resolve_paths(request)
+        artifacts = ArtifactsDir(artifactsdir, latest_dir)
+        artifacts.create()
+
+        if request.chdir:
+            # The child's cwd is about to become artifacts.path, so a
+            # relative executable path (e.g. "./scan.sh") must be resolved
+            # against *this* process's cwd now, or the child would look
+            # for it inside artifacts.path instead.
+            cmd = _resolve_executable(cmd)
+
+        env = os.environ.copy()
+        env["PENRUN_COMMAND"] = shlex.join(cmd)
+        env["PENRUN_ARTIFACTS"] = str(artifacts.path)
+
+        return self._run_command(artifacts, cmd, env, request)
+
+    def _resolve_paths(self, request: RunRequest) -> tuple[Path, Path]:
+        if request.artifactsdir_override is not None:
+            artifactsdir = self._absolute(request.artifactsdir_override)
+            return artifactsdir, artifactsdir.parent
+
+        jobname = request.jobname or self._program_name(request)
+        placeholders = ArtifactsPlaceholders(
+            base=str(self._base_dir(request)),
+            scriptname=self._program_name(request),
+            tag=request.tag,
+            fragment=jobname,
+            jobname=jobname,
+            timestamp=request.timestamp or timestamp_now(),
+        )
+        template = self._config.artifacts_template or self._default_template(request)
+
+        artifactsdir = self._absolute(render_artifactsdir(template, placeholders))
+        return artifactsdir, artifactsdir.parent
+
+    def _default_template(self, request: RunRequest) -> str:
+        if not request.batch:
+            return DEFAULT_TEMPLATE
+        if request.named_jobs:
+            return DEFAULT_BATCH_TEMPLATE_NAMED
+        return DEFAULT_BATCH_TEMPLATE
+
+    def _program_name(self, request: RunRequest) -> str:
+        return request.scriptname or Path(request.cmd[0]).stem
+
+    def _base_dir(self, request: RunRequest) -> Path:
+        base = request.base_override or self._config.artifacts_base or Path.cwd().joinpath("penrun-artifacts")
+        return self._absolute(Path(base))
+
+    def _absolute(self, path: Path) -> Path:
+        return path if path.is_absolute() else Path.cwd().joinpath(path)
+
+    def update_batch_latest(self, request: RunRequest) -> None:
+        # Batch jobs share one run-{timestamp} directory (see
+        # DEFAULT_BATCH_TEMPLATE / DEFAULT_BATCH_TEMPLATE_NAMED), so a
+        # per-job LATEST symlink placed next to it would just have every
+        # job in the batch fight over the same link. Instead, batch mode
+        # gets a single LATEST pointing at that shared run directory - at
+        # the top of the artifacts base normally, or nested under the
+        # command's own directory when -N/--name-by-arg groups jobs under
+        # DEFAULT_BATCH_TEMPLATE_NAMED instead.
+        if request.artifactsdir_override is not None:
+            return
+        artifactsdir, _ = self._resolve_paths(request)
+        run_dir = artifactsdir.parent
+        if request.named_jobs and self._config.artifacts_template is None:
+            latest_dir = run_dir.parent
+        else:
+            latest_dir = self._base_dir(request)
+        update_latest_symlink(latest_dir.joinpath("LATEST"), run_dir)
+
+    def _run_command(
+        self,
+        artifacts: ArtifactsDir,
+        cmd: list[str],
+        env: dict[str, str],
+        request: RunRequest,
+    ) -> int:
+        if not request.batch:
+            artifacts.update_latest_symlink()
+
+        start = now_iso()
+        sinks = PipelineSinks(
+            raw_out_path=artifacts.output_path(),
+            mirror_to_stdout=request.mirror_to_stdout,
+        )
+        cwd = artifacts.path if request.chdir else None
+        exit_code = run_pipeline(cmd, env, sinks, cwd=cwd)
+        end = now_iso()
+
+        artifacts_env = env if request.include_env else None
+        artifacts.write_meta(
+            command=cmd,
+            start_time=start,
+            end_time=end,
+            exit_code=exit_code,
+            env=artifacts_env,
+        )
+        return exit_code