nur 0.1.0__py3-none-any.whl

nur/__init__.py

@@ -0,0 +1,5 @@
+"""Nur — script discovery and execution engine."""
+
+from nur._version import __version__
+
+__all__ = ["__version__"]

nur/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

nur/cli.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+
+import nur
+from nur.discovery import discover
+from nur.execution import run_direct
+from nur.registry import AmbiguousTaskError, Registry, UnknownTaskError
+
+app = typer.Typer(
+    add_completion=False, context_settings={"help_option_names": ["-h", "--help"]}
+)
+
+
+def split_passthrough(argv: list[str]) -> tuple[list[str], list[str]]:
+    """Split argv on the first ``--`` into task args and passthrough args."""
+    if "--" in argv:
+        i = argv.index("--")
+        return argv[:i], argv[i + 1 :]
+    return list(argv), []
+
+
+def format_list(registry: Registry) -> str:
+    """Render the discovered tasks grouped by provider prefix."""
+    lines: list[str] = []
+    for prefix, tasks in registry.groups().items():
+        lines.append(prefix)
+        for task in tasks:
+            desc = f"  {task.description}" if task.description else ""
+            lines.append(f"  {task.name}{desc}")
+    return "\n".join(lines)
+
+
+def _version_callback(value: bool) -> None:
+    # Eager option: print the version and exit before the command body runs.
+    if value:
+        typer.echo(nur.__version__)
+        raise typer.Exit(0)
+
+
+@app.command()
+def _run(
+    ctx: typer.Context,
+    task: str | None = typer.Argument(
+        None, help="task to run, e.g. 'test' or 'make:test'; 'list' to list"
+    ),
+    version: bool = typer.Option(  # noqa: ARG001  (consumed by the eager callback)
+        False,  # noqa: FBT003
+        "-V",
+        "--version",
+        help="print version and exit",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Discover and run a project task, or launch the TUI when none is given."""
+    # Passthrough args (everything after ``--``) are stashed on the context by main().
+    extra: list[str] = ctx.obj["extra"] if ctx.obj else []
+    cwd = Path.cwd()
+
+    registry = discover(cwd)
+
+    if task == "list":
+        typer.echo(format_list(registry))
+        raise typer.Exit(0)
+
+    if task is None:
+        if registry.is_empty():
+            typer.echo("nur: no supported task files found in this directory.")
+            raise typer.Exit(0)
+        # Lazy import — keeps the direct-run path from paying Textual's import cost.
+        from nur.tui.app import launch  # noqa: PLC0415
+
+        raise typer.Exit(launch(registry, cwd))
+
+    try:
+        resolved = registry.resolve(task)
+    except AmbiguousTaskError as exc:
+        typer.echo(
+            f"nur: '{exc.name}' is ambiguous; candidates: {', '.join(exc.candidates)}",
+            err=True,
+        )
+        raise typer.Exit(2) from exc
+    except UnknownTaskError as exc:
+        msg = f"nur: unknown task '{exc.query}'"
+        if exc.suggestions:
+            msg += f"; did you mean: {', '.join(exc.suggestions)}?"
+        typer.echo(msg, err=True)
+        raise typer.Exit(2) from exc
+
+    raise typer.Exit(run_direct(resolved, extra, cwd))
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point: parse args with Typer, returning an int instead of exiting.
+
+    Typer/Click raise ``SystemExit`` for help, version, and every command exit;
+    catching it here keeps ``main``'s int contract so it stays usable from tests
+    and embedders. Passthrough args are handed to the command via ``ctx.obj``.
+    """
+    raw = sys.argv[1:] if argv is None else argv
+    left, extra = split_passthrough(raw)
+    try:
+        app(args=left, prog_name="nur", obj={"extra": extra})
+    except SystemExit as exc:
+        if exc.code is None:  # pragma: no cover - Typer always exits with an int code
+            return 0
+        return exc.code if isinstance(exc.code, int) else 2
+    return 0  # pragma: no cover - Typer's app() always raises SystemExit

nur/discovery.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from nur.providers import PROVIDERS
+from nur.registry import Registry
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from nur.models import Provider, Task
+
+log = logging.getLogger("nur")
+
+
+def discover(cwd: Path, providers: list[Provider] | None = None) -> Registry:
+    providers = PROVIDERS if providers is None else providers
+    tasks: list[Task] = []
+    for provider in providers:
+        try:
+            if provider.detect(cwd):
+                tasks.extend(provider.discover(cwd))
+        # Backstop: a provider must never break discovery for the others.
+        except Exception as exc:  # pylint: disable=broad-exception-caught
+            log.warning("nur: provider %r failed (%s)", provider.prefix, exc)
+    return Registry(tasks)

nur/execution.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import contextlib
+import os
+import signal
+import subprocess
+import sys
+import threading
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+    from nur.models import Task
+
+# Conventional "command not found" exit status (as used by POSIX shells).
+RUNNER_NOT_FOUND = 127
+
+
+def run_direct(task: Task, extra_args: list[str], cwd: Path) -> int:
+    """Run a task with inherited stdio; return the child's exit code.
+
+    A natively-parsed provider (npm/PDM/poe) can surface a task whose runner
+    binary is not installed. Rather than letting ``FileNotFoundError`` escape
+    as a traceback, report a controlled error and return ``127``.
+    """
+    argv = task.run_argv(extra_args)
+    try:
+        completed = subprocess.run(argv, cwd=cwd, check=False)
+    except FileNotFoundError:
+        print(
+            f"nur: runner '{argv[0]}' is not installed "
+            f"(needed to run {task.qualified_name}).",
+            file=sys.stderr,
+        )
+        return RUNNER_NOT_FOUND
+    return completed.returncode
+
+
+class ProcessRunner:
+    """Runs a command with combined output captured and streamed line-by-line.
+
+    Blocking; intended to be driven from a background thread by the TUI.
+    """
+
+    def __init__(self) -> None:
+        self._proc: subprocess.Popen[str] | None = None
+        self._lock = threading.Lock()
+
+    def run(self, argv: list[str], cwd: Path, on_line: Callable[[str], None]) -> int:
+        # Put the child in its own process group so an interrupt can signal the
+        # whole tree (e.g. npm -> node, make -> sh), not just the runner PID:
+        # start_new_session on POSIX, CREATE_NEW_PROCESS_GROUP on Windows. Each
+        # flag is a no-op on the other platform, so both are always passed.
+        creationflags = 0
+        start_new_session = False
+        if sys.platform == "win32":
+            creationflags = subprocess.CREATE_NEW_PROCESS_GROUP
+        else:
+            start_new_session = True
+        # Not a `with` block: the process is stored on self and outlives this
+        # method so interrupt() can signal it; cleanup happens in the finally.
+        try:
+            proc = subprocess.Popen(  # pylint: disable=consider-using-with
+                argv,
+                cwd=cwd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                stdin=subprocess.DEVNULL,
+                text=True,
+                bufsize=1,
+                creationflags=creationflags,
+                start_new_session=start_new_session,
+            )
+        except FileNotFoundError:
+            # Natively-discovered task whose runner isn't installed: surface a
+            # message in the output pane instead of an empty pane + exited(1).
+            on_line(f"nur: runner '{argv[0]}' is not installed.\n")
+            return RUNNER_NOT_FOUND
+        with self._lock:
+            self._proc = proc
+        try:
+            assert proc.stdout is not None
+            for line in proc.stdout:
+                on_line(line)
+        finally:
+            # Runs even if on_line raises, so we never leak the pipe or the
+            # child and never leave stale runner state behind.
+            # stdout is always a PIPE here, so the None branch never runs.
+            if proc.stdout is not None:  # pragma: no branch
+                proc.stdout.close()
+            code = proc.wait()
+            with self._lock:
+                self._proc = None
+        return code
+
+    # interrupt() drives OS signals against a live child, so it is exercised
+    # manually (see tests/tui/test_app_execution.py) rather than in unit tests.
+    def interrupt(self) -> None:  # pragma: no cover
+        with self._lock:
+            proc = self._proc
+        if proc is None or proc.poll() is not None:
+            return
+        # if/else (not an early return) so type checkers treat each arm as a
+        # platform-specific branch and don't flag the other as unreachable.
+        if sys.platform == "win32":
+            # Windows has no os.killpg; CTRL_BREAK is the documented way to
+            # interrupt a CREATE_NEW_PROCESS_GROUP child (and, unlike CTRL_C,
+            # it targets only the child's group, never nur's own console).
+            with contextlib.suppress(OSError):
+                proc.send_signal(signal.CTRL_BREAK_EVENT)
+        else:
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGINT)
+            except OSError:
+                # Process already gone (ProcessLookupError), or the group could
+                # not be signalled (PermissionError) -- both subclass OSError;
+                # fall back to signalling the process directly.
+                with contextlib.suppress(ProcessLookupError, OSError):
+                    proc.send_signal(signal.SIGINT)

nur/models.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class Task:
+    name: str
+    prefix: str
+    argv_base: tuple[str, ...]
+    description: str | None = None
+    definition: str = ""
+    source_file: str = ""
+    # Tokens inserted before passthrough args when (and only when) extra args
+    # are forwarded, e.g. npm requires `npm run <script> -- <args>`.
+    passthrough_prefix: tuple[str, ...] = ()
+
+    @property
+    def qualified_name(self) -> str:
+        return f"{self.prefix}:{self.name}"
+
+    def run_argv(self, extra_args: list[str] | None = None) -> list[str]:
+        extra = extra_args or []
+        separator = self.passthrough_prefix if extra else ()
+        return [*self.argv_base, *separator, *extra]
+
+
+@runtime_checkable
+class Provider(Protocol):
+    prefix: str
+
+    def detect(self, cwd: Path) -> bool: ...
+
+    def discover(self, cwd: Path) -> list[Task]: ...

nur/providers/__init__.py

@@ -0,0 +1,30 @@
+from typing import TYPE_CHECKING
+
+from nur.providers.just import JustProvider
+from nur.providers.make import MakeProvider
+from nur.providers.npm import NpmProvider
+from nur.providers.pdm import PdmProvider
+from nur.providers.poe import PoeProvider
+from nur.providers.task import TaskfileProvider
+
+if TYPE_CHECKING:
+    from nur.models import Provider
+
+PROVIDERS: list[Provider] = [
+    NpmProvider(),
+    MakeProvider(),
+    PdmProvider(),
+    PoeProvider(),
+    JustProvider(),
+    TaskfileProvider(),
+]
+
+__all__ = [
+    "PROVIDERS",
+    "JustProvider",
+    "MakeProvider",
+    "NpmProvider",
+    "PdmProvider",
+    "PoeProvider",
+    "TaskfileProvider",
+]

nur/providers/just.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from typing import TYPE_CHECKING, Any
+
+from nur.models import Task
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+log = logging.getLogger("nur")
+
+
+def parse_dump(text: str, source_file: str = "justfile") -> list[Task]:
+    data = json.loads(text)
+    tasks: list[Task] = []
+    recipes: dict[str, Any] = data.get("recipes") or {}
+    for name, recipe in recipes.items():
+        tasks.append(
+            Task(
+                name=name,
+                prefix="just",
+                argv_base=("just", name),
+                description=recipe.get("doc"),
+                source_file=source_file,
+            )
+        )
+    return tasks
+
+
+class JustProvider:
+    prefix = "just"
+
+    def _source_file(self, cwd: Path) -> str:
+        return "justfile" if (cwd / "justfile").is_file() else "Justfile"
+
+    def detect(self, cwd: Path) -> bool:
+        return (cwd / "justfile").is_file() or (cwd / "Justfile").is_file()
+
+    def discover(self, cwd: Path) -> list[Task]:
+        try:
+            result = subprocess.run(
+                ["just", "--dump", "--dump-format", "json"],
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except OSError:
+            log.warning("nur: 'just' not installed; skipping justfile tasks")
+            return []
+        try:
+            return parse_dump(result.stdout, self._source_file(cwd))
+        except (json.JSONDecodeError, AttributeError) as exc:
+            log.warning("nur: skipping justfile (%s)", exc)
+            return []

nur/providers/make.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import logging
+import re
+from typing import TYPE_CHECKING
+
+from nur.models import Task
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+log = logging.getLogger("nur")
+
+# A rule's left-hand side: one or more target names before ':' or '::'.
+# The negative lookahead excludes variable assignments (':=', '='); recipe
+# lines are tab-indented so they never start with [A-Za-z0-9].
+_RULE_RE = re.compile(r"^([A-Za-z0-9][^:=#]*?)\s*::?(?!=)")
+# A single valid target name (excludes '%' pattern rules and '.'-prefixed).
+_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]*$")
+# An inline "## description" anywhere on the line.
+_DESC_RE = re.compile(r"##\s*(.*?)\s*$")
+
+
+def _targets_on_line(line: str) -> tuple[list[str], str | None]:
+    """Return (target names, description) for one Makefile line.
+
+    Handles multiple targets sharing a rule, e.g. ``build test: ## desc``.
+    """
+    match = _RULE_RE.match(line)
+    if not match:
+        return [], None
+    names = [
+        token
+        for token in match.group(1).split()
+        if _NAME_RE.match(token) and token != "Makefile"
+    ]
+    desc_match = _DESC_RE.search(line)
+    return names, (desc_match.group(1) if desc_match else None)
+
+
+def parse_targets(text: str) -> list[str]:
+    """Extract target names from Makefile *text* without executing anything.
+
+    Deliberately does NOT shell out to ``make``: the database dump
+    (``make -pRrq``) still evaluates ``$(shell ...)`` / ``!=`` assignments while
+    reading the file, so a repository's Makefile could run arbitrary commands
+    merely by discovering/listing tasks. Text parsing is safe, at the cost of
+    not resolving ``include`` directives or computed targets.
+    """
+    names: list[str] = []
+    seen: set[str] = set()
+    for line in text.splitlines():
+        for name in _targets_on_line(line)[0]:
+            if name not in seen:
+                seen.add(name)
+                names.append(name)
+    return names
+
+
+def parse_descriptions(text: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for line in text.splitlines():
+        names, desc = _targets_on_line(line)
+        if desc:
+            for name in names:
+                out.setdefault(name, desc)
+    return out
+
+
+class MakeProvider:
+    prefix = "make"
+
+    def detect(self, cwd: Path) -> bool:
+        return (cwd / "Makefile").is_file()
+
+    def discover(self, cwd: Path) -> list[Task]:
+        try:
+            text = (cwd / "Makefile").read_text()
+        except OSError as exc:
+            log.warning("nur: skipping Makefile (%s)", exc)
+            return []
+        descriptions = parse_descriptions(text)
+        return [
+            Task(
+                name=name,
+                prefix=self.prefix,
+                argv_base=("make", name),
+                description=descriptions.get(name),
+                source_file="Makefile",
+            )
+            for name in parse_targets(text)
+        ]

nur/providers/npm.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from nur.models import Task
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+log = logging.getLogger("nur")
+
+# (lockfile, package manager) in precedence order. Bun writes a text `bun.lock`
+# by default since 1.2 and the legacy binary `bun.lockb` with `--save-text-lockfile`
+# disabled; recognize both.
+_LOCKFILES: tuple[tuple[str, str], ...] = (
+    ("bun.lock", "bun"),
+    ("bun.lockb", "bun"),
+    ("pnpm-lock.yaml", "pnpm"),
+    ("yarn.lock", "yarn"),
+    ("package-lock.json", "npm"),
+)
+
+
+def resolve_pm(cwd: Path) -> str:
+    for lockfile, pm in _LOCKFILES:
+        if (cwd / lockfile).exists():
+            return pm
+    return "npm"
+
+
+class NpmProvider:
+    prefix = "npm"
+
+    def detect(self, cwd: Path) -> bool:
+        return (cwd / "package.json").is_file()
+
+    def discover(self, cwd: Path) -> list[Task]:
+        try:
+            data = json.loads((cwd / "package.json").read_text())
+        except (OSError, json.JSONDecodeError) as exc:
+            log.warning("nur: skipping package.json (%s)", exc)
+            return []
+        # Annotated Any (not dict) so the runtime isinstance guard below stays
+        # meaningful: package.json "scripts" may not be an object.
+        scripts: Any = data.get("scripts") or {}
+        if not isinstance(scripts, dict):
+            log.warning("nur: skipping package.json ('scripts' is not an object)")
+            return []
+        pm = resolve_pm(cwd)
+        return [
+            Task(
+                name=name,
+                prefix=self.prefix,
+                argv_base=(pm, "run", name),
+                definition=str(command),
+                source_file="package.json",
+                # npm requires `npm run <script> -- <args>`; pnpm/yarn/bun accept
+                # the `--` separator too, so emit it uniformly when forwarding.
+                passthrough_prefix=("--",),
+            )
+            for name, command in scripts.items()
+        ]

nur/providers/pdm.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import logging
+import tomllib
+from typing import TYPE_CHECKING, Any
+
+from nur.models import Task
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+log = logging.getLogger("nur")
+
+
+def _load_scripts(cwd: Path) -> dict[str, object] | None:
+    """Return the [tool.pdm.scripts] table, or None if absent/unreadable."""
+    path = cwd / "pyproject.toml"
+    try:
+        data = tomllib.loads(path.read_text())
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        log.warning("nur: skipping pyproject.toml (%s)", exc)
+        return None
+    tool = data.get("tool", {})
+    pdm: dict[str, Any] = tool.get("pdm", {}) if isinstance(tool, dict) else {}
+    scripts = pdm.get("scripts") if isinstance(pdm, dict) else None
+    return scripts if isinstance(scripts, dict) else None
+
+
+def _definition_and_help(value: object) -> tuple[str, str | None]:
+    if isinstance(value, dict):
+        body = value.get("cmd") or value.get("shell") or value.get("call") or ""
+        if isinstance(body, list):
+            body = " ".join(str(x) for x in body)
+        help_val = value.get("help")
+        return str(body), (help_val if isinstance(help_val, str) else None)
+    return str(value), None
+
+
+class PdmProvider:
+    prefix = "pdm"
+
+    def detect(self, cwd: Path) -> bool:
+        scripts = _load_scripts(cwd)
+        return bool(scripts)
+
+    def discover(self, cwd: Path) -> list[Task]:
+        scripts = _load_scripts(cwd)
+        if not scripts:
+            return []
+        tasks: list[Task] = []
+        for name, value in scripts.items():
+            if name == "_":  # PDM reserved global-options key
+                continue
+            definition, help_text = _definition_and_help(value)
+            tasks.append(
+                Task(
+                    name=name,
+                    prefix=self.prefix,
+                    argv_base=("pdm", "run", name),
+                    description=help_text,
+                    definition=definition,
+                    source_file="pyproject.toml",
+                )
+            )
+        return tasks