renforge 0.1.0__py3-none-any.whl

renforge/__init__.py

@@ -0,0 +1,4 @@
+"""RenForge package."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

renforge/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

renforge/activity_log.py

@@ -0,0 +1,93 @@
+"""Activity feed helpers for MCP tool calls."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+
+def _coerce_project_root(project_root: str | Path) -> Path:
+    return Path(project_root).expanduser().resolve()
+
+
+def _coerce_files_touched(value: Any) -> list[str]:
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, (list, tuple, set)):
+        return [str(item) for item in value if isinstance(item, (str, Path))]
+    return []
+
+
+def _coerce_result_payload(result: Any) -> Any:
+    if isinstance(result, dict) and "ok" in result:
+        return result
+    if isinstance(result, (str, int, float, bool, list, type(None))):
+        return result
+    return str(result)
+
+
+def _coerce_payload(value: Any) -> Any:
+    if isinstance(value, (str, int, float, bool, type(None))):
+        return value
+    if isinstance(value, list):
+        return [_coerce_payload(item) for item in value]
+    if isinstance(value, dict):
+        return {str(k): _coerce_payload(v) for k, v in value.items()}
+    if isinstance(value, set):
+        return sorted(str(item) for item in value)
+    if isinstance(value, tuple):
+        return [_coerce_payload(item) for item in value]
+    return str(value)
+
+
+def summarize_result(result: Any) -> dict[str, Any]:
+    if isinstance(result, dict):
+        ok = result.get("ok", not isinstance(result.get("error"), str))
+        files_touched: list[str] = []
+        for key in ("files_touched", "files", "changed_files", "changed", "file_touches"):
+            candidate = result.get(key)
+            if candidate:
+                files_touched = _coerce_files_touched(candidate)
+                break
+        return {"ok": bool(ok), "files_touched": files_touched, "result": result}
+
+    if isinstance(result, (str, int, float, bool, list, type(None))):
+        return {"ok": True, "files_touched": [], "result": result}
+
+    return {"ok": True, "files_touched": [], "result": str(result)}
+
+
+def log_tool_call(
+    project_root: str | Path,
+    name: str,
+    params: dict[str, Any],
+    duration_ms: float,
+    result: Any,
+    files_touched: list[str] | None = None,
+) -> None:
+    summary = summarize_result(result)
+    entry = {
+        "ts": int(time.time() * 1000),
+        "name": name,
+        "params": _coerce_payload(params),
+        "duration_ms": duration_ms,
+        "ok": summary["ok"],
+        "result": _coerce_result_payload(summary["result"]),
+        "files_touched": files_touched or summary["files_touched"],
+    }
+
+    root = _coerce_project_root(project_root)
+    if not root.exists() or not root.is_dir():
+        return
+    path = root / ".renforge" / "activity.jsonl"
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = json.dumps(entry, ensure_ascii=False, separators=(",", ":"))
+    with path.open("a", encoding="utf-8") as file_obj:
+        file_obj.write(payload)
+        file_obj.write("\n")
+        file_obj.flush()
+        os.fsync(file_obj.fileno())

renforge/assets.py

@@ -0,0 +1,149 @@
+"""Asset analysis: find orphaned and missing images/audio in a Ren'Py project.
+
+Heuristic and deliberately conservative — Ren'Py's image resolution is dynamic
+(``show eileen happy`` maps to a defined image or a file like
+``images/eileen happy.png``), so this reports *likely* orphans/missing rather
+than a proof. It reads the ``game/`` tree and the ``.rpy`` sources; the engine
+stays the source of truth via ``lint``.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".webp", ".gif", ".avif", ".tga", ".bmp"}
+AUDIO_EXTS = {".ogg", ".opus", ".mp3", ".wav", ".flac", ".m4a", ".aac", ".mp2", ".wma"}
+VIDEO_EXTS = {".webm", ".mp4", ".ogv", ".avi", ".mkv", ".mov", ".mpg", ".mpeg", ".flv"}
+ASSET_EXTS = IMAGE_EXTS | AUDIO_EXTS | VIDEO_EXTS
+
+_QUOTED_RE = re.compile(r"""["']([^"'\n]+?)["']""")
+_IMAGE_DEF_RE = re.compile(r"^\s*image\s+([^\n=:]+?)\s*(?:=|:)")
+_SCENE_SHOW_RE = re.compile(r"^\s*(?:scene|show)\s+(.+?)\s*(?:#.*)?$")
+# Tokens that end the image-name part of a scene/show statement.
+_SHOW_STOP = {"at", "with", "as", "behind", "onlayer", "zorder", "expression"}
+
+
+def _game_dir(project_path: str | Path) -> Path:
+    return Path(project_path).expanduser().resolve() / "game"
+
+
+def _iter_rpy(game: Path):
+    for root, _dirs, files in os.walk(game):
+        for name in files:
+            if name.endswith(".rpy"):
+                yield Path(root) / name
+
+
+def _image_name_from_show(rest: str) -> str:
+    tokens = rest.split()
+    keep: list[str] = []
+    for tok in tokens:
+        if tok in _SHOW_STOP:
+            break
+        keep.append(tok)
+    return " ".join(keep)
+
+
+def analyze_assets(project_path: str | Path) -> dict[str, Any]:
+    game = _game_dir(project_path)
+    result: dict[str, Any] = {
+        "asset_files": [],
+        "orphans": [],
+        "missing_files": [],
+        "undefined_images": [],
+    }
+    if not game.is_dir():
+        result["error"] = f"no game/ directory under {project_path}"
+        return result
+
+    # 1. Asset files on disk (relative to game/, posix-style).
+    disk_files: list[str] = []
+    for root, _dirs, files in os.walk(game):
+        for name in files:
+            if Path(name).suffix.lower() in ASSET_EXTS:
+                rel = (Path(root) / name).relative_to(game).as_posix()
+                disk_files.append(rel)
+    disk_files.sort()
+    result["asset_files"] = disk_files
+
+    # 2. References from the scripts.
+    quoted: set[str] = set()
+    defined_images: set[str] = set()
+    shown_images: set[str] = set()
+    for rpy in _iter_rpy(game):
+        try:
+            text = rpy.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for line in text.splitlines():
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            for m in _QUOTED_RE.finditer(line):
+                quoted.add(m.group(1))
+            dm = _IMAGE_DEF_RE.match(line)
+            if dm:
+                defined_images.add(dm.group(1).strip())
+            sm = _SCENE_SHOW_RE.match(line)
+            if sm:
+                name = _image_name_from_show(sm.group(1))
+                if name:
+                    shown_images.add(name)
+
+    quoted_basenames = {Path(q).name for q in quoted}
+
+    def _referenced(rel: str) -> bool:
+        base = Path(rel).name
+        stem = Path(rel).stem  # image name candidate, e.g. "eileen happy"
+        if rel in quoted or base in quoted_basenames:
+            return True
+        if any(q.endswith(rel) or q.endswith(base) for q in quoted):
+            return True
+        # Image files referenced via `scene/show <name>` or `image <name>`.
+        if Path(rel).suffix.lower() in IMAGE_EXTS:
+            if stem in shown_images or stem in defined_images:
+                return True
+        return False
+
+    result["orphans"] = [rel for rel in disk_files if not _referenced(rel)]
+
+    # 3. Missing: quoted references that look like *developer* asset paths but
+    #    aren't on disk. We skip substitution patterns ("[prefix_]...") and the
+    #    gui/ tree, whose images the GUI framework generates or renders by
+    #    default — flagging those would be noise, not actionable findings.
+    disk_set = set(disk_files)
+    disk_basenames = {Path(f).name for f in disk_files}
+    for q in sorted(quoted):
+        if "[" in q or "]" in q:
+            continue
+        if q.startswith("gui/"):
+            continue
+        if Path(q).suffix.lower() in ASSET_EXTS:
+            if q not in disk_set and Path(q).name not in disk_basenames:
+                result["missing_files"].append(q)
+
+    # 4. Images shown but neither defined nor backed by a file (Ren'Py would use
+    #    a placeholder). Reported separately as a soft signal.
+    disk_stems = {Path(f).stem for f in disk_files if Path(f).suffix.lower() in IMAGE_EXTS}
+    for name in sorted(shown_images):
+        if name in defined_images:
+            continue
+        # A single-tag show may resolve to "<first-tag>.png"; check tag stems too.
+        first = name.split()[0] if name.split() else name
+        if name in disk_stems or first in disk_stems or first in defined_images:
+            continue
+        result["undefined_images"].append(name)
+
+    result["summary"] = {
+        "asset_count": len(disk_files),
+        "orphan_count": len(result["orphans"]),
+        "missing_count": len(result["missing_files"]),
+        "undefined_image_count": len(result["undefined_images"]),
+    }
+    return result
+
+
+__all__ = ["analyze_assets"]

renforge/autopilot.py

@@ -0,0 +1,171 @@
+"""Autopilot: explore a Ren'Py visual novel and report label coverage + crashes.
+
+Strategy — systematic branch exploration by replay. Each run launches the game
+fresh, replays a fixed prefix of menu choices, then at the first *new* menu it
+takes choice 0 and queues the remaining choices as future runs. Repeating until
+the frontier is empty covers every branch combination, using only primitives
+that work reliably (launch / advance / list_choices / select_choice /
+poll_events) — no in-game save/load, which cannot be driven from the bridge's
+main-thread callback.
+
+Menus are detected by ``list_choices`` returning options. (A game with an
+always-on quick menu could surface non-choice buttons here; refining detection
+to the active ``choice`` screen is a future improvement.)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections import deque
+from pathlib import Path
+from typing import Any, Callable
+
+from .bridge.launcher import launch_with_bridge
+from .project import RenpyProject
+from .scanner import scan_project
+from .sdk import RenpySdk
+
+
+def _story_labels(project_path: str | Path) -> set[str]:
+    # Labels authored in the project, excluding Ren'Py-internal (underscore) ones.
+    index = scan_project(str(project_path))
+    return {label["name"] for label in index.get("labels", []) if not label["name"].startswith("_")}
+
+
+def _menu_choices(client) -> list[dict]:
+    """Choices that belong to the active ``choice`` screen (ignores quick menu)."""
+    return [c for c in client.list_choices() if c.get("screen") == "choice"]
+
+
+def autopilot(
+    sdk: RenpySdk,
+    project: RenpyProject,
+    *,
+    max_runs: int = 16,
+    max_steps: int = 60,
+    settle: float = 0.4,
+    startup_timeout: float = 90.0,
+    progress_callback: Callable[[dict], None] | None = None,
+) -> dict[str, Any]:
+    """Explore the game and return a coverage/crash report.
+
+    After each run a partial report is written to
+    ``<project>/.renforge/autopilot.json`` and passed to ``progress_callback``
+    (if given), so long explorations can be followed incrementally.
+    """
+    total_labels = _story_labels(project.root)
+
+    reached: set[str] = set()
+    dialogue: set[str] = set()
+    crashes: list[dict] = []
+    choices_explored = 0
+
+    frontier: deque[list[int]] = deque([[]])
+    seen_prefixes: set[tuple[int, ...]] = set()
+    runs = 0
+
+    progress_path = project.cache_dir / "autopilot.json"
+
+    def _report(done: bool) -> dict[str, Any]:
+        covered = sorted(total_labels & reached)
+        return {
+            "ok": True,
+            "done": done,
+            "runs": runs,
+            "runs_pending": len(frontier),
+            "labels_total": len(total_labels),
+            "labels_reached": sorted(reached),
+            "labels_covered": covered,
+            "labels_unreached": sorted(total_labels - reached),
+            "coverage": round(len(covered) / len(total_labels), 3) if total_labels else 1.0,
+            "dialogue_lines": len(dialogue),
+            "choices_explored": choices_explored,
+            "crashes": crashes,
+        }
+
+    def _emit(done: bool) -> None:
+        report = _report(done)
+        try:
+            progress_path.write_text(json.dumps(report), encoding="utf-8")
+        except OSError:
+            pass
+        if progress_callback is not None:
+            try:
+                progress_callback(report)
+            except Exception:
+                pass
+
+    def _drain(client, cursor: int, run_labels: list[str]) -> int:
+        events = client.poll_events(since=cursor)
+        for event in events["events"]:
+            kind = event.get("type")
+            if kind == "label":
+                name = event.get("label")
+                if name and not name.startswith("_"):
+                    reached.add(name)
+                    run_labels.append(name)
+            elif kind == "say":
+                dialogue.add(event.get("what"))
+            elif kind == "exception":
+                crashes.append({"short": event.get("short"), "full": event.get("full")})
+        return events["cursor"]
+
+    while frontier and runs < max_runs:
+        prefix = frontier.popleft()
+        if tuple(prefix) in seen_prefixes:
+            continue
+        seen_prefixes.add(tuple(prefix))
+        runs += 1
+
+        session = launch_with_bridge(sdk, project, startup_timeout=startup_timeout)
+        try:
+            cursor = 0
+            seq: list[int] = list(prefix)
+            seq_pos = 0
+            run_labels: list[str] = []
+
+            for _step in range(max_steps):
+                cursor = _drain(session.client, cursor, run_labels)
+
+                # Loop guard: a repeated story label means the game cycled back
+                # (e.g. returned to the main menu); stop this run so we don't
+                # keep re-answering the same menu forever.
+                if len(run_labels) != len(set(run_labels)):
+                    break
+
+                choices = _menu_choices(session.client)
+                if choices:
+                    # Let the menu's show transition finish so the choice buttons
+                    # are at stable positions before we click one.
+                    time.sleep(settle)
+                    choices = _menu_choices(session.client) or choices
+                    if seq_pos < len(seq):
+                        idx = seq[seq_pos]
+                    else:
+                        # New branch point: take choice 0, queue the alternatives.
+                        for alt in range(1, len(choices)):
+                            frontier.append(seq + [alt])
+                        idx = 0
+                        seq.append(0)
+                    seq_pos += 1
+                    idx = min(idx, len(choices) - 1)
+                    # Select by visible text (the reliable focus-resolution path).
+                    session.client.select_choice(text=choices[idx]["text"])
+                    choices_explored += 1
+                    time.sleep(settle)
+                    continue
+
+                session.client.advance()
+                time.sleep(settle)
+
+            _drain(session.client, cursor, run_labels)
+        finally:
+            session.close()
+
+        _emit(done=not frontier or runs >= max_runs)
+
+    return _report(done=True)
+
+
+__all__ = ["autopilot"]

renforge/bridge/__init__.py

@@ -0,0 +1,10 @@
+"""Bridge utilities for future real-time Ren'Py TCP communication."""
+
+from .client import BridgeClient, BridgeConfig, BridgeError, BridgeProtocolError
+
+__all__ = [
+    "BridgeClient",
+    "BridgeConfig",
+    "BridgeError",
+    "BridgeProtocolError",
+]