rung-cli 0.1.2__py3-none-any.whl

rung/cli/commands/setup.py

@@ -0,0 +1,174 @@
+"""Commands that set a project up: init, plan, doctor, agents, hook."""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+from rung import agents
+from rung.analysis import plan, survey
+from rung.checks.presets import PRESETS
+from rung.cli.commands.common import OK, ask
+from rung.cli.output import Output
+from rung.core import laws
+from rung.core.config import CONFIG_NAME, Check, Config, ConfigError, LLMConfig, find_root, load, save
+from rung.core.errors import ToolMissing
+from rung.drafting import providers
+from rung.engines import lean, tla
+
+
+def _choose_provider(requested: str | None) -> LLMConfig:
+    if requested:
+        return LLMConfig(provider=requested)
+    options = providers.detect()
+    # Prompts go to stderr so `--json` output on stdout stays one clean document.
+    print("\nWhich model should draft specs, proofs and explanations?", file=sys.stderr)
+    for i, name in enumerate(options, 1):
+        print(f"  {i}. {name:18} {providers.PROVIDERS[name]}", file=sys.stderr)
+    picked = ask("Choose", "1")
+    name = options[int(picked) - 1] if picked.isdigit() and 0 < int(picked) <= len(options) else picked
+    if name not in providers.PROVIDERS:
+        raise ConfigError(f"unknown provider {name!r}")
+    llm = LLMConfig(provider=name)
+    if name == "openai-compatible":
+        llm.base_url = ask("Base URL", "http://localhost:11434/v1")
+        llm.model = ask("Model name", "qwen2.5-coder")
+    return llm
+
+
+def cmd_init(args, out: Output) -> int:
+    root = Path(args.dir).resolve()
+    existing = (root / CONFIG_NAME).exists()
+    cfg = load(root) if existing else Config(root=root, name=root.name, llm=LLMConfig(), checks=[])
+    info = survey.survey(root)
+
+    if not existing or args.provider:
+        cfg.llm = _choose_provider(args.provider)
+    if args.model is not None:
+        cfg.llm.model = args.model
+    provider = providers.get(cfg.llm)
+    state = provider.login_state()
+    needs_login = not state.ok and cfg.llm.provider in ("claude-cli", "codex-cli")
+    if needs_login and ask("Not logged in. Log in now? (y/n)", "y").lower().startswith("y"):
+        provider.login()
+        state = provider.login_state()
+
+    added = []
+    if not existing:
+        # Wire up the security scanners that are installed and relevant to this repo.
+        for check_id, tool in (
+            ("secrets", "gitleaks"),
+            ("vulnerable-deps", "osv-scanner"),
+            ("workflows", "zizmor"),
+        ):
+            relevant = tool != "zizmor" or (root / ".github" / "workflows").is_dir()
+            if shutil.which(tool) and relevant:
+                cfg.checks.append(Check(check_id, "scan", [], {"tool": tool}))
+                added.append(check_id)
+        cfg.checks.append(Check("deps", "deps", [], {"min_age_days": 30}))
+        added.append("deps")
+        # Record each detected test suite, covering its own project directory.
+        for project in info.projects:
+            if not project.test_command:
+                continue
+            check_id = plan.static_check_id(project.path, "tests")
+            options = {"run": project.test_command} | ({} if project.path == "." else {"cwd": project.path})
+            covers = [] if project.path == "." else [f"{project.path}/**"]
+            cfg.checks.append(Check(check_id, "command", covers, options))
+            added.append(check_id)
+        # The type checkers and linters the project already configures, and the shortcuts that silence them.
+        for project in info.projects:
+            for kind, command in project.static:
+                check_id = plan.static_check_id(project.path, kind)
+                if any(c.id == check_id for c in cfg.checks):
+                    continue
+                options = {"run": command} | ({} if project.path == "." else {"cwd": project.path})
+                covers = [] if project.path == "." else [f"{project.path}/**"]
+                cfg.checks.append(Check(check_id, "command", covers, options))
+                added.append(check_id)
+        if info.languages:
+            cfg.checks.append(Check("shortcuts", "shortcuts", [], {}))
+            added.append("shortcuts")
+
+    save(cfg)
+    (root / ".rung").mkdir(exist_ok=True)
+    if not (root / laws.LAWS_FILE).exists():
+        (root / laws.LAWS_FILE).write_text(laws.TEMPLATE)
+    recs = plan.plan(info, {c.id for c in cfg.checks})
+    out.emit({"root": str(root), "provider": cfg.llm.provider, "login": state.detail,
+              "added_checks": added, "survey": info.to_dict(), "plan": [r.__dict__ for r in recs]})  # fmt: skip
+    langs = ", ".join(f"{k} ({v})" for k, v in list(info.languages.items())[:4]) or "none found"
+    out.line(f"Surveyed {root}")
+    out.line(f"  languages: {langs}")
+    out.line(f"  surfaces:  {', '.join(info.surfaces) or 'none found'}")
+    out.line(f"  tests:     {', '.join(info.test_commands) or 'none found'}")
+    out.line(f"Model provider: {cfg.llm.provider} ({state.detail})")
+    if added:
+        out.line(f"Added checks: {', '.join(added)}")
+    out.line(f"Wrote {CONFIG_NAME}, {laws.LAWS_FILE} and .rung/.")
+    _print_plan(recs, out)
+    out.line("\nNext: `rung agents --hooks`, then `rung check`.")
+    return OK
+
+
+def _print_plan(recs: list[plan.Recommendation], out: Output) -> None:
+    out.line("\nRecommended next steps:")
+    for i, rec in enumerate(recs, 1):
+        out.line(f"\n {i}. {out.style(rec.title, 'bold')}  [{rec.rung}, effort {rec.effort}]")
+        out.detail(rec.why, indent=4)
+        if rec.command:
+            out.line(f"    {out.style('$ ' + rec.command, 'blue')}")
+
+
+def cmd_plan(args, out: Output) -> int:
+    root = Path(args.dir).resolve()
+    try:
+        existing = {c.id for c in load(find_root(root)).checks}
+    except ConfigError:
+        existing = set()
+    info = survey.survey(root)
+    recs = plan.plan(info, existing)
+    out.emit({"survey": info.to_dict(), "plan": [r.__dict__ for r in recs]})
+    _print_plan(recs, out)
+    return OK
+
+
+def cmd_doctor(args, out: Output) -> int:
+    rows: list[tuple[str, bool, str]] = []
+    for label, probe in (
+        ("java (TLC)", tla.find_java),
+        ("tla2tools.jar", tla.find_jar),
+        ("lake (Lean)", lean.find_lake),
+    ):
+        try:
+            rows.append((label, True, str(probe())))
+        except ToolMissing as exc:
+            rows.append((label, False, str(exc)))
+    for name, preset in PRESETS.items():
+        found = shutil.which(name)
+        note = "" if preset.verified else " (preset not yet verified against real output)"
+        rows.append((name, bool(found), (found or f"not installed: {preset.install}") + note))
+    for name in ("claude-cli", "codex-cli"):
+        state = providers.get(LLMConfig(provider=name)).login_state()
+        rows.append((name, state.ok, state.detail))
+    out.emit([{"tool": label, "ok": ok, "detail": detail} for label, ok, detail in rows])
+    for label, ok, detail in rows:
+        mark = out.style("ok ", "green") if ok else out.style("-- ", "dim")
+        out.line(f"{mark} {label:14} {detail}")
+    return OK
+
+
+def cmd_agents(args, out: Output) -> int:
+    root = find_root(Path(args.dir))
+    written = agents.install(root, hooks=args.hooks, lean_version=lean.toolchain().split(":")[-1])
+    out.emit({"written": [str(p.relative_to(root)) for p in written]})
+    for path in written:
+        out.line(f"wrote {path.relative_to(root)}")
+    if args.hooks:
+        out.line("Claude Code will now run `rung hook stop` before an agent finishes.")
+    return OK
+
+
+def cmd_hook(args, out: Output) -> int:
+    return agents.main_stop_hook()

rung/cli/output.py

@@ -0,0 +1,54 @@
+"""Terminal output: colour when attached to a terminal, plain text otherwise, JSON on request."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+_CODES = {"red": "31", "green": "32", "yellow": "33", "blue": "34", "dim": "2", "bold": "1"}
+VERDICT_STYLE = {"pass": ("PASS", "green"), "fail": ("FAIL", "red"), "error": ("ERROR", "yellow")}
+STATE_STYLE = {
+    "fresh": ("fresh", "green"),
+    "stale": ("STALE", "yellow"),
+    "failing": ("FAILING", "red"),
+    "never": ("never run", "dim"),
+    "held": ("HELD", "green"),
+    "unproven": ("UNPROVEN", "yellow"),
+    "broken": ("BROKEN", "red"),
+    "proposed": ("PROPOSED", "blue"),
+    "unenforced": ("UNENFORCED", "dim"),
+}
+
+
+class Output:
+    def __init__(self, *, json_mode: bool = False, color: bool | None = None) -> None:
+        self.json_mode = json_mode
+        if color is None:
+            color = sys.stdout.isatty() and "NO_COLOR" not in os.environ and os.environ.get("TERM") != "dumb"
+        self.color = color
+
+    def style(self, text: str, name: str) -> str:
+        return f"\033[{_CODES[name]}m{text}\033[0m" if self.color else text
+
+    def badge(self, key: str, table: dict[str, tuple[str, str]], width: int = 9) -> str:
+        label, colour = table.get(key, (key, "dim"))
+        return self.style(label.ljust(width), colour)
+
+    def line(self, text: str = "") -> None:
+        if not self.json_mode:
+            print(text)
+
+    def detail(self, text: str, indent: int = 6) -> None:
+        if not self.json_mode:
+            for part in text.splitlines() or [""]:
+                print(" " * indent + part)
+
+    def emit(self, payload: Any) -> None:
+        """In JSON mode, print the command's result as one JSON document."""
+        if self.json_mode:
+            print(json.dumps(payload, indent=2, default=str))
+
+    def error(self, text: str) -> None:
+        print(f"rung: {text}", file=sys.stderr)

rung/core/__init__.py

@@ -0,0 +1 @@
+"""Foundations every other layer builds on: configuration, the ledger, laws, git and errors."""

rung/core/config.py

@@ -0,0 +1,278 @@
+"""`rung.toml`: the project's declared checks and model provider.
+
+The file is small and hand-editable. Rung reads it with `tomllib`, validates every field it
+understands before running anything, and writes it with a serializer that covers the shapes
+Rung itself produces. A check's id becomes part of file paths (baselines, evidence), so ids are
+restricted to letters, digits, `.`, `_` and `-`.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import os
+import re
+import shlex
+import tempfile
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from rung.core.errors import RungError
+
+CONFIG_NAME = "rung.toml"
+CHECK_KINDS = ("command", "evidence", "scan", "shortcuts", "deps", "tla", "lean", "drt")
+CHECK_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}\Z")
+# Options that must be non-negative integers wherever they appear.
+INT_OPTIONS = ("timeout", "cases", "min_len", "max_len", "seed", "min_age_days")
+# Options that must be lists of strings wherever they appear.
+LIST_OPTIONS = ("specs", "require", "allow", "theorems", "alphabet")
+# Every option each kind understands; anything else is a typo that would otherwise do nothing.
+COMMON_OPTIONS = ("timeout", "max_age_days", "specs", "drafted_by")
+KIND_OPTIONS = {
+    "command": ("run", "cwd"),
+    "evidence": ("run", "cwd", "require"),
+    "scan": ("tool", "run", "cwd", "fail_on", "default_level"),
+    "shortcuts": ("allow", "fail_on"),
+    "deps": ("allow", "min_age_days"),
+    "tla": ("spec", "config"),
+    "lean": ("project", "theorems"),
+    "drt": ("model", "impl", "model_cwd", "impl_cwd", "alphabet", "cases", "min_len", "max_len", "seed"),
+}
+
+
+class ConfigError(RungError, ValueError):
+    """`rung.toml` is missing, malformed, or declares an invalid check."""
+
+
+@dataclass
+class Check:
+    """One verification check: a spec, a proof, a differential test, or a command."""
+
+    id: str
+    kind: str
+    covers: list[str] = field(default_factory=list)
+    options: dict[str, Any] = field(default_factory=dict)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.options.get(key, default)
+
+    def require(self, key: str) -> Any:
+        if key not in self.options:
+            raise ConfigError(f"check {self.id!r} ({self.kind}) needs `{key}`")
+        return self.options[key]
+
+    def get_int(self, key: str, default: int) -> int:
+        value = self.options.get(key, default)
+        if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+            raise ConfigError(f"check {self.id!r}: `{key}` must be a non-negative integer, not {value!r}")
+        return value
+
+    def get_list(self, key: str) -> list[str]:
+        value = self.options.get(key, [])
+        if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+            raise ConfigError(f"check {self.id!r}: `{key}` must be a list of strings")
+        return value
+
+
+@dataclass
+class LLMConfig:
+    provider: str = "none"
+    model: str = ""
+    base_url: str = ""
+    api_key_env: str = "RUNG_API_KEY"
+
+
+@dataclass
+class Config:
+    root: Path
+    name: str
+    llm: LLMConfig
+    checks: list[Check]
+
+    def check(self, check_id: str) -> Check:
+        for c in self.checks:
+            if c.id == check_id:
+                return c
+        raise ConfigError(f"no check named {check_id!r} in {CONFIG_NAME}")
+
+
+def find_root(start: Path) -> Path:
+    """Walk up from `start` to the directory holding `rung.toml`."""
+    start = start.resolve()
+    for d in (start, *start.parents):
+        if (d / CONFIG_NAME).is_file():
+            return d
+    raise ConfigError(f"no {CONFIG_NAME} in {start} or its parents; run `rung init`")
+
+
+def _unquoted_tokens(command: str) -> list[str]:
+    """Tokens with quoted text removed, so `node -e "a();"` is not mistaken for shell syntax."""
+    lexer = shlex.shlex(command, posix=False, punctuation_chars=False)
+    lexer.whitespace_split = True
+    try:
+        return [t for t in lexer if not (len(t) >= 2 and t[0] == t[-1] and t[0] in "'\"")]
+    except ValueError:
+        return command.split()
+
+
+SHELL_TOKENS = {"&&", "||", "|", ";", ">", ">>", "<", "2>", "2>&1", "&"}
+SHELLS = {"sh", "bash", "zsh", "dash", "fish", "cmd", "powershell", "pwsh"}
+
+
+def safe_id(text: str) -> str:
+    """A check id made from a path or name: unsupported characters become `-`."""
+    return re.sub(r"[^A-Za-z0-9._-]+", "-", text).strip("-.")[:64] or "check"
+
+
+def check_command(check_id: str, key: str, command: str) -> None:
+    """Commands run without a shell. Reject shell syntax instead of passing it to a program as arguments.
+
+    Without this, `cd src && pytest` runs `/usr/bin/cd` on macOS, which ignores its arguments and
+    exits 0: a pass that never ran the tests.
+    """
+    try:
+        argv = shlex.split(command)
+    except ValueError as exc:
+        raise ConfigError(f"check {check_id!r}: `{key}` is not a valid command ({exc})") from exc
+    if not argv:
+        raise ConfigError(f"check {check_id!r}: `{key}` is empty")
+    if Path(argv[0]).name in SHELLS:
+        return  # an explicit shell, e.g. sh -c "cd src && pytest", is the supported way
+    problem = ""
+    bare = _unquoted_tokens(command)
+    if any(t in SHELL_TOKENS or t.startswith(("$(", "`")) or t.endswith(";") or "&&" in t or "||" in t for t in bare):
+        problem = "uses shell syntax (&&, |, ;, redirects)"
+    elif "=" in argv[0] and not argv[0].startswith(("-", "/", ".")):
+        problem = "starts with an environment assignment"
+    elif argv[0] == "cd":
+        problem = "starts with `cd` (use the check's `cwd` option instead)"
+    if problem:
+        raise ConfigError(
+            f"check {check_id!r}: `{key}` {problem}, but commands run without a shell. "
+            f'Use `cwd`, or wrap it explicitly: sh -c "{command}"'
+        )
+
+
+def _validate_check(check: Check) -> None:
+    known = (*COMMON_OPTIONS, *KIND_OPTIONS[check.kind])
+    for key in check.options:
+        if key not in known:
+            close = difflib.get_close_matches(key, (*known, "covers"), n=1)
+            hint = f"; did you mean `{close[0]}`?" if close else f"; {check.kind} checks take {', '.join(known)}"
+            raise ConfigError(f"check {check.id!r}: unknown option `{key}`{hint}")
+    for key in INT_OPTIONS:
+        if key in check.options:
+            check.get_int(key, 0)
+    for key in LIST_OPTIONS:
+        if key in check.options:
+            check.get_list(key)
+    for key in ("run", "cwd", "tool", "spec", "config", "project", "model", "impl", "fail_on", "default_level",
+                "model_cwd", "impl_cwd"):  # fmt: skip
+        if key in check.options and not isinstance(check.options[key], str):
+            raise ConfigError(f"check {check.id!r}: `{key}` must be a string")
+    for key in ("run", "model", "impl"):
+        if key in check.options:
+            check_command(check.id, key, check.options[key])
+
+
+def load(root: Path) -> Config:
+    path = root / CONFIG_NAME
+    try:
+        raw = tomllib.loads(path.read_text())
+    except FileNotFoundError as exc:
+        raise ConfigError(f"{path} not found; run `rung init`") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{path}: {exc}") from exc
+
+    llm_raw = raw.get("llm", {})
+    if not isinstance(llm_raw, dict):
+        raise ConfigError("[llm] must be a table")
+    llm = LLMConfig(**{k: str(v) for k, v in llm_raw.items() if k in LLMConfig.__dataclass_fields__})
+
+    entries = raw.get("check", [])
+    if not isinstance(entries, list):
+        raise ConfigError("checks are declared as [[check]] tables")
+    checks: list[Check] = []
+    seen: set[str] = set()
+    for i, entry in enumerate(entries):
+        entry = dict(entry)
+        check_id = entry.pop("id", None)
+        kind = entry.pop("kind", None)
+        if not check_id or not kind:
+            raise ConfigError(f"[[check]] #{i + 1} needs both `id` and `kind`")
+        if not isinstance(check_id, str) or not CHECK_ID.match(check_id):
+            raise ConfigError(f"check id {check_id!r} must be letters, digits, `.`, `_` or `-` (at most 64)")
+        if kind not in CHECK_KINDS:
+            raise ConfigError(f"check {check_id!r}: kind must be one of {', '.join(CHECK_KINDS)}")
+        if check_id in seen:
+            raise ConfigError(f"duplicate check id {check_id!r}")
+        seen.add(check_id)
+        covers = entry.pop("covers", [])
+        if not isinstance(covers, list) or not all(isinstance(p, str) for p in covers):
+            raise ConfigError(f'check {check_id!r}: `covers` must be a list of glob strings, e.g. ["src/**"]')
+        check = Check(id=check_id, kind=kind, covers=covers, options=entry)
+        _validate_check(check)
+        checks.append(check)
+
+    project = raw.get("project", {})
+    name = (project.get("name") if isinstance(project, dict) else None) or root.name
+    return Config(root=root, name=str(name), llm=llm, checks=checks)
+
+
+def toml_value(value: Any) -> str:
+    """A TOML literal for the values Rung writes. Strings use JSON escaping, which is valid TOML."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return repr(value)
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(toml_value(v) for v in value) + "]"
+    raise TypeError(f"cannot write {type(value).__name__} to TOML")
+
+
+def dump(config: Config) -> str:
+    lines = ["[project]", f"name = {toml_value(config.name)}", "", "[llm]"]
+    for key in ("provider", "model", "base_url", "api_key_env"):
+        lines.append(f"{key} = {toml_value(getattr(config.llm, key))}")
+    for c in config.checks:
+        lines += ["", "[[check]]", f"id = {toml_value(c.id)}", f"kind = {toml_value(c.kind)}"]
+        for key, value in c.options.items():
+            lines.append(f"{key} = {toml_value(value)}")
+        lines.append(f"covers = {toml_value(c.covers)}")
+    return "\n".join(lines) + "\n"
+
+
+def write_atomic(path: Path, text: str) -> None:
+    """Replace `path` in one step, so a crash never leaves a half-written file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.")
+    try:
+        # mkstemp creates the file 0600; keep the existing mode, or use the usual 0644.
+        os.chmod(tmp, path.stat().st_mode & 0o7777 if path.exists() else 0o644)
+        with os.fdopen(fd, "w") as fh:
+            fh.write(text)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def save(config: Config) -> Path:
+    """Write `rung.toml`. Comments are not preserved; the file is regenerated from the parsed config.
+
+    Every check is validated exactly as `load` will validate it, so a command can never save a
+    configuration that the next command rejects.
+    """
+    for check in config.checks:
+        if not CHECK_ID.match(check.id):
+            raise ConfigError(f"check id {check.id!r} must be letters, digits, `.`, `_` or `-` (at most 64)")
+        _validate_check(check)
+    text = dump(config)
+    tomllib.loads(text)  # never write a file Rung itself could not read back
+    path = config.root / CONFIG_NAME
+    write_atomic(path, text)
+    return path

rung/core/errors.py

@@ -0,0 +1,9 @@
+"""Errors shared across Rung."""
+
+
+class RungError(Exception):
+    """Base class for errors Rung reports to the user without a traceback."""
+
+
+class ToolMissing(RungError):
+    """A required external tool (java, tla2tools.jar, lake, a scanner, a model CLI) is not installed."""