factorio-mod-workshop 0.1.0__py3-none-any.whl

fmw/config.py

@@ -0,0 +1,187 @@
+"""Workspace discovery and configuration.
+
+All mod-specific and personal data lives in a *workspace* directory that is
+deliberately kept outside this repository (see `fmw help workspace`).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from importlib.resources import as_file, files
+from pathlib import Path
+from typing import ContextManager
+
+import yaml
+
+try:  # libyaml is ~5x faster and ships with the PyYAML wheel on common platforms
+    from yaml import CSafeLoader as _Loader
+except ImportError:  # pragma: no cover - pure-python fallback
+    from yaml import SafeLoader as _Loader
+
+
+def yaml_load(text: str):
+    """Parse YAML with the fastest available loader."""
+    return yaml.load(text, Loader=_Loader)
+
+
+WORKSPACE_ENV = "FMW_WORKSPACE"
+
+
+class WorkspaceError(RuntimeError):
+    pass
+
+
+def template_dir() -> ContextManager[Path]:
+    """The bundled workspace scaffold, as a context manager yielding a path.
+
+    Resolved as a package resource rather than by walking up from __file__, so
+    it works identically for editable installs, wheels and zipapps, and does
+    not silently break when the package layout changes.
+    """
+    return as_file(files(__package__) / "templates" / "workspace")
+
+
+def locate_workspace(explicit: str | None = None) -> Path:
+    """Resolve the workspace directory.
+
+    Priority: --workspace, then $FMW_WORKSPACE. There is deliberately no
+    implicit fallback: a workspace is real data, and guessing which one is
+    meant is worse than saying so.
+    """
+    for source, value in (("--workspace", explicit), (f"${WORKSPACE_ENV}", os.environ.get(WORKSPACE_ENV))):
+        if not value:
+            continue
+        path = Path(value).expanduser()
+        if not path.is_dir():
+            raise WorkspaceError(f"{source} points at {path}, which does not exist. Create it with `fmw init {path}`.")
+        return path.resolve()
+    raise WorkspaceError(
+        f"No workspace given. Set ${WORKSPACE_ENV}, pass --workspace PATH, or run "
+        "`fmw launcher` once to get a wrapper that pins one."
+    )
+
+
+@dataclass
+class Workspace:
+    root: Path
+
+    @classmethod
+    def open(cls, explicit: str | None = None) -> "Workspace":
+        return cls(locate_workspace(explicit))
+
+    # --- paths ---
+    @property
+    def mods_file(self) -> Path:
+        return self.root / "mods.yaml"
+
+    @property
+    def config_file(self) -> Path:
+        return self.root / "config.yaml"
+
+    @property
+    def paths_file(self) -> Path:
+        return self.root / "paths.yaml"
+
+    @property
+    def threads_dir(self) -> Path:
+        return self.root / "threads"
+
+    @property
+    def cache_dir(self) -> Path:
+        return self.root / "cache"
+
+    @property
+    def tracker_dir(self) -> Path:
+        return self.root / "tracker"
+
+    def mod_cache_dir(self, mod: str) -> Path:
+        return self.cache_dir / mod
+
+    def thread_file(self, mod: str, thread_id: str) -> Path:
+        return self.mod_cache_dir(mod) / "threads" / f"{thread_id}.json"
+
+    def list_file(self, mod: str) -> Path:
+        return self.mod_cache_dir(mod) / "threads.json"
+
+    def mod_tracker_dir(self, mod: str) -> Path:
+        return self.tracker_dir / mod
+
+    # --- documents ---
+    def load_config(self) -> dict:
+        if not self.config_file.exists():
+            return {}
+        return yaml_load(self.config_file.read_text()) or {}
+
+    def mod_repos(self) -> list[str]:
+        return [str(r) for r in (self.load_config().get("mod_repos") or [])]
+
+    def edit_mod_repos(self, add: str | None = None, remove: str | None = None) -> list[str]:
+        """Add or remove a repository, editing config.yaml in place.
+
+        Line-oriented rather than parse-and-dump on purpose: config.yaml is
+        hand-written and full of comments, and PyYAML cannot round-trip those.
+        Rewriting the file would silently delete the explanations it ships with.
+        """
+        if not self.config_file.exists():
+            self.config_file.write_text("mod_repos:\n")
+        lines = self.config_file.read_text().splitlines()
+
+        head = next((i for i, l in enumerate(lines)
+                     if re.match(r"^mod_repos:\s*(\[\s*\])?\s*$", l)), None)
+        if head is None:
+            lines += ["", "mod_repos:"]
+            head = len(lines) - 1
+        lines[head] = "mod_repos:"          # normalise an empty `mod_repos: []`
+
+        end = head + 1
+        while end < len(lines) and re.match(r"^\s*-\s+\S", lines[end]):
+            end += 1
+        items = lines[head + 1:end]
+
+        if remove is not None:
+            target = str(Path(remove).expanduser())
+            items = [i for i in items
+                     if str(Path(i.strip()[1:].strip()).expanduser()) != target]
+        if add is not None:
+            existing = {str(Path(i.strip()[1:].strip()).expanduser()) for i in items}
+            if str(Path(add).expanduser()) not in existing:
+                items.append(f"  - {add}")
+
+        self.config_file.write_text("\n".join(lines[:head + 1] + items + lines[end:]) + "\n")
+        return [i.strip()[1:].strip() for i in items]
+
+    def load_mods(self) -> dict:
+        if not self.mods_file.exists():
+            return {"mods": {}}
+        data = yaml_load(self.mods_file.read_text()) or {}
+        data.setdefault("mods", {})
+        from .discover import normalise_maintained  # local: avoids a cycle
+        for entry in data["mods"].values():
+            if "maintained" in entry:
+                entry["maintained"] = normalise_maintained(entry["maintained"])
+        return data
+
+    def load_paths(self) -> dict[str, str]:
+        """Local checkout paths, keyed by mod name. Machine-specific."""
+        if not self.paths_file.exists():
+            return {}
+        data = yaml_load(self.paths_file.read_text()) or {}
+        return data.get("paths") or {}
+
+    def save_paths(self, paths: dict[str, str]) -> None:
+        header = (
+            "# Where each mod is checked out on THIS machine. Generated by `fmw discover`.\n"
+            "# Kept out of mods.yaml so the registry can be shared; gitignored by default.\n"
+        )
+        self.paths_file.write_text(
+            header + yaml.safe_dump({"paths": dict(sorted(paths.items()))},
+                                    sort_keys=False, allow_unicode=True, width=100)
+        )
+
+    def save_mods(self, data: dict) -> None:
+        self.mods_file.parent.mkdir(parents=True, exist_ok=True)
+        self.mods_file.write_text(
+            yaml.safe_dump(data, sort_keys=False, allow_unicode=True, width=100)
+        )

fmw/discover.py

@@ -0,0 +1,193 @@
+"""Build the mod registry by scanning local repositories and the portal API."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .config import Workspace
+from .portal import NotFound, Portal, PortalError
+
+
+SKIP_DIRS = {"node_modules", ".git", ".venv", "__pycache__"}
+
+
+def scan_local(
+    roots: list[Path], max_depth: int = 3
+) -> tuple[list[dict], list[str]]:
+    """Find Factorio mods under the given roots, plus a list of warnings.
+
+    A mod is any directory holding a readable info.json with a `name` and a
+    `version`, which is what the game itself requires. Returns entries and
+    warnings describing everything that was skipped, so a silently ignored
+    typo in an info.json does not look like a mod that simply is not there.
+    """
+    found: list[dict] = []
+    warnings: list[str] = []
+    seen: dict[str, Path] = {}
+    for root in roots:
+        root = root.expanduser().resolve()
+        if not root.is_dir():
+            warnings.append(f"{root}: not a directory, skipped")
+            continue
+        for info_path in sorted(root.rglob("info.json")):
+            rel = info_path.relative_to(root)
+            if len(rel.parts) > max_depth:
+                continue
+            # Only the part below the root matters; the root's own ancestors
+            # may legitimately contain any of these names.
+            if any(part in SKIP_DIRS for part in rel.parts):
+                continue
+            try:
+                info = json.loads(info_path.read_text())
+            except (json.JSONDecodeError, UnicodeDecodeError, OSError) as exc:
+                warnings.append(f"{info_path}: unreadable ({type(exc).__name__}), skipped")
+                continue
+            name = info.get("name")
+            if not name or "version" not in info:
+                warnings.append(f"{info_path}: no 'name' or 'version', not a mod, skipped")
+                continue
+            if name in seen:
+                warnings.append(
+                    f"mod '{name}' found twice: using {seen[name]}, ignoring {info_path.parent}"
+                )
+                continue
+            seen[name] = info_path.parent
+            found.append(
+                {
+                    "name": name,
+                    "title": info.get("title", name),
+                    "local_version": info.get("version"),
+                    "factorio_version": str(info.get("factorio_version", "")),
+                    "path": str(info_path.parent),
+                    "repo": str(root),
+                    "contact": info.get("contact", ""),
+                    "homepage": info.get("homepage", ""),
+                }
+            )
+    return found, warnings
+
+
+def enrich_from_portal(portal: Portal, entries: list[dict]) -> list[str]:
+    """Add portal-side facts to each registry entry. Returns warnings."""
+    warnings: list[str] = []
+    for e in entries:
+        try:
+            info = portal.mod_info(e["name"])
+        except NotFound:
+            e["on_portal"] = False
+            warnings.append(f"{e['name']}: not published on the mod portal")
+            continue
+        except PortalError as exc:
+            # A network failure must not be recorded as "unpublished" - leave
+            # the previous answer alone and say the lookup did not happen.
+            warnings.append(f"{e['name']}: portal lookup failed ({exc})")
+            continue
+        e["on_portal"] = True
+        e["title"] = info.get("title", e.get("title"))
+        e["downloads"] = info.get("downloads_count")
+        e["category"] = info.get("category", "")
+        releases = info.get("releases") or []
+        if releases:
+            latest = releases[-1]
+            e["portal_version"] = latest.get("version")
+            e["portal_factorio_version"] = (latest.get("info_json") or {}).get(
+                "factorio_version", ""
+            )
+            e["portal_released_at"] = (latest.get("released_at") or "")[:10]
+        e["portal_url"] = f"https://mods.factorio.com/mod/{e['name']}"
+    return warnings
+
+
+# Fields the local scan always knows, and so always refreshes.
+LOCAL_FIELDS = {
+    "local_version": "",
+    "factorio_version": "",
+}
+# Fields only a portal lookup can supply. With --no-portal they are absent from
+# the scanned entry, and must then be carried over from the previous registry
+# rather than reset - otherwise an offline run silently discards them.
+PORTAL_FIELDS = {
+    "portal_version": "",
+    "portal_factorio_version": "",
+    "portal_released_at": "",
+    "downloads": 0,
+    "category": "",
+    "on_portal": None,
+}
+# Fields the maintainer owns; never touched by a scan.
+MANUAL_FIELDS = ("maintained", "notes", "discord", "aliases", "priority")
+
+# Deliberately words YAML cannot coerce. `yes` and `no` are parsed by YAML 1.1
+# as booleans, which silently broke every string comparison against this field.
+MAINTAINED = ("active", "frozen", "unknown")
+
+LEGACY_MAINTAINED = {
+    True: "active", "yes": "active",
+    False: "frozen", "no": "frozen",
+    "frozen": "frozen",
+}
+
+
+def normalise_maintained(value) -> str:
+    """Map any historical spelling onto the current vocabulary."""
+    if isinstance(value, str):
+        value = value.strip().lower()
+    if value in LEGACY_MAINTAINED:
+        return LEGACY_MAINTAINED[value]
+    return value if value in MAINTAINED else "unknown"
+
+
+
+
+def build_registry(existing: dict, entries: list[dict]) -> dict:
+    """Merge discovered entries into the registry, preserving what a scan cannot know."""
+    mods = existing.get("mods") or {}
+    for e in entries:
+        name = e["name"]
+        prev = mods.get(name) or {}
+        merged: dict = {
+            "title": e.get("title") or prev.get("title") or name,
+            "maintained": normalise_maintained(prev.get("maintained")),
+            "portal_url": f"https://mods.factorio.com/mod/{name}",
+        }
+        for field, default in LOCAL_FIELDS.items():
+            merged[field] = e.get(field, prev.get(field, default))
+        for field, default in PORTAL_FIELDS.items():
+            merged[field] = e[field] if field in e else prev.get(field, default)
+        for field in MANUAL_FIELDS:
+            if field in prev:
+                merged[field] = prev[field]
+        merged.setdefault("notes", "")
+        mods[name] = merged
+    existing["mods"] = dict(sorted(mods.items(), key=lambda kv: -(kv[1].get("downloads") or 0)))
+    return existing
+
+
+def sync_paths(ws: Workspace, entries: list[dict]) -> dict[str, str]:
+    """Record where each mod lives on this machine, in paths.yaml.
+
+    Kept out of mods.yaml so the registry stays free of machine-specific data
+    and can be committed and shared. Paths recorded by an earlier version are
+    migrated out of the registry on the first run.
+    """
+    paths = ws.load_paths()
+    registry = ws.load_mods()["mods"]
+    for name, entry in registry.items():
+        if entry.get("path") and name not in paths:
+            paths[name] = entry["path"]
+    for e in entries:
+        if e.get("path"):
+            paths[e["name"]] = e["path"]
+    ws.save_paths(paths)
+    return paths
+
+
+def strip_legacy_paths(registry: dict) -> bool:
+    """Remove the old per-mod `path` field. Returns True if anything changed."""
+    changed = False
+    for entry in registry.get("mods", {}).values():
+        if "path" in entry:
+            del entry["path"]
+            changed = True
+    return changed