tmodloader-mcp 0.6.0__py3-none-any.whl

tmodloader_mcp/api.py

@@ -0,0 +1,262 @@
+"""Searching the tModLoader API surface without a browser or a guess.
+
+WHY THIS EXISTS. Writing mod-side code here has meant answering two questions
+over and over: does this member exist, and what does it take. Both have been
+answered badly. "Does `Main.cloudAlpha` exist" was answered by GREPPING A 21MB
+DLL FOR A SUBSTRING, which finds the name and cannot say what owns it, whether
+it is a field or a method, or what type it is. "What does `QuickSpawnItem`
+take" was answered by writing the call and letting the compiler decide - exact,
+but only for code already written, and a build cycle per attempt.
+
+Neither answers the question you have BEFORE writing anything: what is there.
+`Main.maxRaining` is only findable if you already suspect the name.
+
+WHAT THIS IS NOT: documentation. It is the assembly's own public surface, read
+from its metadata, so it cannot drift from the version installed - which is the
+failure mode of every wiki page and every model's recollection. It carries no
+prose, because it is not trying to explain anything.
+
+The index is built by `tools/ApiIndex`, which reads metadata WITHOUT loading or
+running the assembly, and cached against the DLL it came from so a tModLoader
+update invalidates it by construction rather than by anybody remembering.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import Config
+
+#: One line per member: `path`, `kind`, `type`. Tab separated because the paths
+#: contain every other punctuation character a signature can hold.
+_FIELDS = 3
+
+#: What a caller may filter by, which is the second column of the index.
+KINDS = ("type", "field", "property", "method")
+
+
+class ApiError(RuntimeError):
+    """The index cannot be built or read, and the message says what to do."""
+
+
+@dataclass(frozen=True)
+class Member:
+    """One line of the index, split.
+
+    `path` is what is searched and what a caller reads back — the fully
+    qualified name, with a method's parameters attached. Namespaces are kept:
+    `Terraria.Main` and a mod's own `Main` are different types, and an index
+    that called both "Main" would confidently answer about the wrong one.
+    """
+
+    path: str
+    kind: str
+    type: str
+
+    @property
+    def name(self) -> str:
+        """The short name, without the namespace or the parameter list.
+
+        What a human means when they say "cloudAlpha". Used for ranking, so an
+        exact hit on the thing somebody typed sorts above a signature that
+        merely mentions it somewhere.
+        """
+        head = self.path.split("(", 1)[0]
+        return head.rsplit(".", 1)[-1]
+
+
+def parse(text: str) -> list[Member]:
+    """Split an index into members, skipping anything malformed.
+
+    Skipped rather than raised on: an index is thousands of lines produced by a
+    separate program, and one unreadable line is not a reason to refuse every
+    question about the other thirty-six thousand.
+    """
+    out: list[Member] = []
+    for line in text.splitlines():
+        parts = line.split("\t")
+        if len(parts) != _FIELDS:
+            continue
+        out.append(Member(path=parts[0], kind=parts[1], type=parts[2]))
+    return out
+
+
+def search(
+    members: list[Member], query: str, *, kind: str | None = None, limit: int = 40
+) -> list[Member]:
+    """Members matching `query`, best first.
+
+    RANKED, because an unranked substring search over 36,000 members answers
+    "rain" with `slimeRainKillCount` before `raining` and buries the thing
+    somebody asked for. The order is: the short name IS the query, then the
+    short name contains it, then it appears anywhere else — a match inside a
+    parameter list is a real match and a worse one.
+
+    Case-insensitive throughout, matching every other filter here.
+    """
+    if not query or not query.strip():
+        raise ValueError(
+            "search needs something to look for. An empty query matches all "
+            "36,000 members, which is the index rather than an answer"
+        )
+
+    if kind is not None and kind not in KINDS:
+        raise ValueError(f"{kind!r} is not one of {', '.join(KINDS)}")
+
+    needle = query.strip().lower()
+    scored: list[tuple[int, int, str, Member]] = []
+
+    for member in members:
+        if kind is not None and member.kind != kind:
+            continue
+
+        name = member.name.lower()
+        path = member.path.lower()
+
+        if name == needle:
+            rank = 0
+        elif needle in name:
+            rank = 1
+        elif needle in path:
+            rank = 2
+        elif needle in member.type.lower():
+            rank = 3
+        else:
+            continue
+
+        # Shorter paths first within a rank: `Terraria.Main.raining` before
+        # `Terraria.GameContent.Something.rainingHelper`, because the shallow
+        # one is nearly always the one being asked about.
+        scored.append((rank, len(member.path), member.path, member))
+
+    scored.sort(key=lambda row: (row[0], row[1], row[2]))
+    return [row[3] for row in scored[:limit]]
+
+
+def index_path_for(cfg: Config) -> Path:
+    """Where this install's index is cached, keyed by the DLL it describes.
+
+    Size and mtime rather than a hash: the point is to notice a tModLoader
+    update, and reading 21MB to answer a question about a cache is a cost paid
+    on every call to avoid one paid on the rare occasion the game changes.
+
+    Under the user's cache directory rather than in the install or the
+    repository. The install is somebody else's, and a generated file of tens of
+    thousands of lines does not belong in version control.
+    """
+    dll = cfg.tml_dll
+    stamp = dll.stat() if dll.is_file() else None
+    key = f"{stamp.st_size}-{int(stamp.st_mtime)}" if stamp else "absent"
+
+    root = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    return root / "tmodloader-mcp" / f"api-{key}.txt"
+
+
+def _dotnet() -> str:
+    """The SDK used to build and run the indexer, or a refusal naming the need.
+
+    NOT `cfg.dotnet`, which is tModLoader's own bundled runtime: that is a
+    Windows executable for running the game, and this is a build of a small
+    Linux console tool. Different tool, same word.
+    """
+    for candidate in ("dotnet", str(Path.home() / ".dotnet" / "dotnet")):
+        found = shutil.which(candidate) or (
+            candidate if Path(candidate).is_file() else None
+        )
+        if found:
+            return found
+
+    raise ApiError(
+        "no dotnet SDK on PATH, and the API index is built by a small C# tool "
+        "(tools/ApiIndex). Install the .NET 8 SDK, or answer the question with "
+        "a build instead - the compiler is exact about signatures."
+    )
+
+
+def ensure_index(cfg: Config, *, timeout: float = 300.0) -> Path:
+    """The cached index for this install, building it if it is not there.
+
+    Built once per tModLoader version and then read from disk. The build is a
+    `dotnet build` plus a metadata read of the game assembly, which is seconds
+    rather than minutes, but it is not something to do on every question.
+    """
+    cached = index_path_for(cfg)
+    if cached.is_file() and cached.stat().st_size > 0:
+        return cached
+
+    dll = cfg.tml_dll
+    if not dll.is_file():
+        raise ApiError(
+            f"there is no tModLoader.dll at {dll}, so there is no API to index. "
+            "Check TMODLOADER_DIR."
+        )
+
+    tool = Path(__file__).resolve().parent.parent.parent / "tools" / "ApiIndex"
+    if not (tool / "ApiIndex.csproj").is_file():
+        raise ApiError(f"the indexer is missing from {tool}")
+
+    dotnet = _dotnet()
+    cached.parent.mkdir(parents=True, exist_ok=True)
+
+    built = tool / "bin" / "Debug" / "net8.0" / "ApiIndex.dll"
+    if not built.is_file():
+        _run(
+            [dotnet, "build", str(tool), "-v", "q", "--nologo"],
+            timeout=timeout,
+            what="building the API indexer",
+        )
+
+    # INDEXED UNDER A STAGING NAME AND RENAMED, because the validity check
+    # above is `is_file and size > 0` - which a file killed mid-write passes
+    # forever. A SIGTERM landing during the one build this cache ever gets
+    # (and `finally` does not run on SIGTERM here, measured) left a truncated
+    # index that every later call served: `parse` skips the one torn line, so
+    # api_search answered "not found" about every member in the missing tail -
+    # the misleading absence this module exists to prevent, installed
+    # permanently by the process meant to prevent it.
+    staging = cached.with_name(f"{cached.name}.{os.getpid()}.partial")
+    try:
+        _run(
+            [dotnet, str(built), str(dll), str(staging)],
+            timeout=timeout,
+            what="indexing the API",
+        )
+
+        if not staging.is_file() or staging.stat().st_size == 0:
+            raise ApiError(
+                f"the indexer reported success and wrote nothing to {staging}, "
+                "so there is no index to search"
+            )
+
+        staging.replace(cached)
+    finally:
+        staging.unlink(missing_ok=True)
+
+    return cached
+
+
+def _run(command: list[str], *, timeout: float, what: str) -> None:
+    """Run a step, and fail LOUD with what it actually said.
+
+    `check=False` plus an explicit raise rather than `check=True`: a
+    CalledProcessError carries the return code and hides the output, and the
+    output is the only part anybody can act on.
+    """
+    try:
+        proc = subprocess.run(
+            command, capture_output=True, text=True, timeout=timeout, check=False
+        )
+    except subprocess.TimeoutExpired:
+        raise ApiError(f"{what} did not finish within {timeout:.0f}s") from None
+    except OSError as broken:
+        raise ApiError(f"{what} could not start: {broken}") from None
+
+    if proc.returncode != 0:
+        raise ApiError(
+            f"{what} failed ({proc.returncode}):\n"
+            f"{(proc.stdout + proc.stderr).strip()[-2000:]}"
+        )

tmodloader_mcp/build.py

@@ -0,0 +1,141 @@
+"""Building the mod, and reading tModLoader's build output honestly.
+
+WHY THIS IS NOT JUST A subprocess CALL
+
+tModLoader refuses to build while the game is open, and says so with
+`Mod Build error TML003`. That is a completely recoverable situation with an
+obvious fix, and it arrives buried in output that otherwise looks like a
+compiler failure. Surfacing it as itself, with the fix, is most of this module's
+value — the alternative is reading it as a broken build and going looking for a
+syntax error that is not there.
+
+The other half is that "did it succeed" is a QUESTION ABOUT THE OUTPUT, not
+about the exit code, which tModLoader does not use reliably here.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+
+from .config import Config, ConfigError
+
+#: The line tModLoader prints when it will not build over a running game.
+GAME_OPEN_MARKER = "TML003"
+
+#: The line that means the compiler finished, with its counts.
+SUCCESS_MARKER = "Compilation finished with"
+
+
+@dataclass(frozen=True)
+class BuildResult:
+    ok: bool
+    errors: int
+    warnings: int
+    game_was_open: bool
+    output: str
+    #: The build never finished, so there are no counts to report. A state the
+    #: other fields cannot express: a timeout arrives as `errors=0, warnings=0`,
+    #: which is shaped exactly like a build that completed with nothing wrong.
+    #: Recorded rather than inferred, because `summary` was reading those zeros
+    #: as a verdict and announcing a compile failure with no errors in it.
+    timed_out: bool = False
+
+    @property
+    def summary(self) -> str:
+        if self.game_was_open:
+            return (
+                "tModLoader refused to build because the game is open. Close "
+                "tModLoader and build again - this is not a compile failure."
+            )
+        if self.timed_out:
+            # Ahead of the counts, because here they are zero for want of a
+            # build rather than for want of anything wrong with the code.
+            return self.output
+        if not self.ok:
+            return f"build failed: {self.errors} error(s), {self.warnings} warning(s)"
+        return f"Compilation finished with {self.errors} errors and {self.warnings} warnings"
+
+
+def _counts(line: str) -> tuple[int, int]:
+    """Pull the error and warning counts out of the success line."""
+    words = line.replace(",", " ").split()
+    errors = warnings = 0
+    for i, w in enumerate(words):
+        if w.startswith("error") and i:
+            errors = int(words[i - 1]) if words[i - 1].isdigit() else errors
+        if w.startswith("warning") and i:
+            warnings = int(words[i - 1]) if words[i - 1].isdigit() else warnings
+    return errors, warnings
+
+
+def interpret(output: str) -> BuildResult:
+    """Decide what a build's output means.
+
+    Pure, so the interpretation is testable without building anything - which
+    matters because the interesting cases (game open, warnings but no errors)
+    are annoying to reproduce on demand.
+    """
+    game_open = GAME_OPEN_MARKER in output
+
+    for line in output.splitlines():
+        if SUCCESS_MARKER in line:
+            errors, warnings = _counts(line)
+            # A build can print the success line AND still have been refused,
+            # if a previous step got that far. The refusal wins: no .tmod was
+            # written, so reporting success would be a lie about the artifact.
+            return BuildResult(
+                ok=errors == 0 and not game_open,
+                errors=errors,
+                warnings=warnings,
+                game_was_open=game_open,
+                output=output,
+            )
+
+    return BuildResult(
+        ok=False, errors=0, warnings=0, game_was_open=game_open, output=output
+    )
+
+
+def build(cfg: Config, *, timeout: float = 600.0) -> BuildResult:
+    """Build the configured mod source."""
+    if cfg.mod_source_win is None:
+        # Refused here rather than spelled into the command line, where it would
+        # arrive as the literal word "None" and come back as tModLoader failing
+        # to find a directory nobody ever named.
+        raise ConfigError(
+            f"{cfg.mod_source} has no known Windows path, so there is nothing to "
+            "hand `-build`. Set TMODLOADER_MOD_SOURCE_WIN."
+        )
+
+    try:
+        proc = subprocess.run(
+            [
+                str(cfg.tml_dir / "dotnet" / "dotnet.exe"),
+                "tModLoader.dll",
+                "-server",
+                "-build",
+                cfg.mod_source_win,
+            ],
+            cwd=str(cfg.tml_dir),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            # Success is read from the OUTPUT, not the exit code, which is not
+            # reliable here - so a non-zero exit must not raise past the parser.
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return BuildResult(
+            ok=False,
+            errors=0,
+            warnings=0,
+            game_was_open=False,
+            output=(
+                f"the build did not finish within {timeout:.0f}s, so nothing is "
+                "known about whether the code compiles"
+            ),
+            timed_out=True,
+        )
+
+    return interpret(proc.stdout + proc.stderr)

tmodloader_mcp/captures.py

@@ -0,0 +1,204 @@
+"""Reading a capture back out of the save directory, and refusing the rest.
+
+WHY THIS IS NOT `path.read_bytes()`
+
+`shot` hands back a filesystem path, which is worth nothing to an agent that is
+not running on this machine. Returning the bytes is the fix, and doing it
+carelessly is worse than the problem: a tool that opens whatever path it is
+given and returns the contents is a file-exfiltration primitive with an MCP
+interface in front of it.
+
+That is the exact failure this project was built to avoid, arriving from the
+other end. OS-level screen capture was tried first and came back with a Teams
+inbox and a Discord friend list in frame. The answer was to read the game's own
+back buffer, which cannot contain another window BY CONSTRUCTION. A reader that
+will open any file on request gives that guarantee away again.
+
+So containment is structural rather than advisory:
+
+- the caller supplies a NAME, never a path;
+- the result is RESOLVED and its parent compared to the resolved save directory,
+  which is what catches `..`, an absolute path, and a symlink alike. Scanning
+  the name for `..` is a blacklist, and blacklists lose to the first spelling
+  nobody thought of - a symlink contains no `..` at all;
+- and the name must look like a capture, because the save directory also holds
+  diag dumps, heartbeats, trigger files and the world itself. Being in the right
+  directory is not the same as being the right kind of file.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .triggers import PLAYER_TOKEN_GRAMMAR, artifacts_for
+
+
+def capture_pattern(mod_name: str) -> re.Pattern[str]:
+    """What `shot` writes for ONE mod: its artifact prefix, the player token,
+    then the index and region this harness renames the drop box to.
+
+    Anchored at both ends — an unanchored match would accept
+    `evil-biomancy-shot-001-full.png.exe`. Built per mod rather than fixed,
+    because two mods share one save directory and neither should be served the
+    other's captures.
+
+    The token's grammar is PINNED rather than left as `[a-z0-9-]+`. An open
+    token is greedy across dashes and digits alike, so it would swallow the
+    three-digit index and leave the region matching what was meant to be the
+    index — the pattern would still match, and would extract the wrong fields.
+    The four-hex tail is what makes the boundary findable at all.
+
+    Imports `PLAYER_TOKEN_GRAMMAR` from `triggers` rather than holding its own
+    copy: two hand-written copies of a regex are two regexes, and this one has
+    to stay the SAME grammar `triggers` uses or the boundary against the
+    three-digit index stops being findable.
+
+    The PREFIX comes from `artifacts_for` for the same reason and was the same
+    hand-copy one line further down - `mod_name.lower()` is the naming rule
+    restated, and a rule restated is a rule that can diverge from the names
+    actually written.
+    """
+    return re.compile(
+        rf"^{re.escape(artifacts_for(mod_name).prefix)}"
+        rf"-shot-{PLAYER_TOKEN_GRAMMAR}-\d{{3}}-[a-z]+\.png$"
+    )
+
+
+class CaptureError(RuntimeError):
+    """The named capture cannot be served, and the message says which rule."""
+
+
+def available(save_dir: Path, mod_name: str) -> list[str]:
+    """Every capture THIS MOD wrote, sorted, names only.
+
+    Names rather than paths for the same reason `read` takes one: a path handed
+    out is a path that can come back changed.
+    """
+    if not save_dir.is_dir():
+        return []
+
+    pattern = capture_pattern(mod_name)
+    return sorted(
+        entry.name for entry in save_dir.iterdir() if pattern.match(entry.name)
+    )
+
+
+def contained(
+    save_dir: Path, mod_name: str, name: str, *, missing_ok: bool = False
+) -> Path:
+    """The path this name resolves to, or `CaptureError` saying why not.
+
+    THE ONE CONTAINMENT CHECK, because there is now more than one caller and a
+    second copy is how one of them ends up weaker — which this module's own
+    header says about having two paths to one file. `read` returns bytes and
+    `prune` DELETES, so the dangerous caller is the newer one; giving it its
+    own rules is exactly the mistake to avoid.
+
+    The three refusals stay distinct: "that is not a capture name", "that is
+    not inside the save directory", and "that capture is not there" are
+    different mistakes, and collapsing them makes a typo look like a security
+    refusal.
+
+    `missing_ok` relaxes ONLY the third - the name and containment rules hold
+    regardless. It exists for `prune`, whose target set is a listing another
+    session may be shrinking at the same time: a file that vanished between
+    the listing and this check is a delete that is already done, and refusing
+    the whole prune over it turned concurrent housekeeping into a spurious
+    "there is no capture" error.
+    """
+    if not capture_pattern(mod_name).match(name):
+        raise CaptureError(
+            f"{name!r} is not a capture name for {mod_name}. Only files this "
+            f"harness wrote - {artifacts_for(mod_name).prefix}"
+            "-shot-<token>-<index>-<region>.png "
+            "- can be read back; the save directory also holds diag dumps, "
+            "heartbeats, the world, and any other mod's captures."
+        )
+
+    root = save_dir.resolve()
+    target = (root / name).resolve()
+
+    # Compared AFTER resolving, so `..`, an absolute path and a symlink are all
+    # the same case rather than three checks and a fourth nobody wrote.
+    if target.parent != root:
+        raise CaptureError(
+            f"{name!r} resolves to {target}, which is outside {root}. Captures "
+            "are served from the save directory only."
+        )
+
+    if not target.is_file() and not missing_ok:
+        raise CaptureError(f"there is no capture called {name!r} in {root}")
+
+    return target
+
+
+def read(save_dir: Path, mod_name: str, name: str) -> bytes:
+    """The bytes of one capture, or `CaptureError` saying why not."""
+    return contained(save_dir, mod_name, name).read_bytes()
+
+
+def prune(save_dir: Path, mod_name: str, *, keep: int) -> list[str]:
+    """Delete all but the newest `keep` captures, and say which went.
+
+    Captures accumulated forever. `shot` writes one per call and nothing ever
+    removed them, so an agent photographing in a loop grew the user's SAVE
+    DIRECTORY without bound — the folder holding their worlds and characters,
+    which is not a cache and not somewhere to leave litter.
+
+    Every deletion goes through `contained`, so a file is removed only when it
+    matches this mod's capture pattern AND resolves to a direct child of the
+    save directory. Listing and deleting through different rules is how a
+    delete ends up looser than the read beside it.
+
+    Ordered by MTIME rather than by the name's index, because the index is this
+    harness's own counter and the file's timestamp is the disk's account of
+    what actually happened. Ties break on name so the result is deterministic.
+
+    `keep=0` is honoured — "remove all of them" is a real request — but there is
+    deliberately no default here. The caller chooses; a module-level default
+    would be this file deciding how much of someone else's directory to throw
+    away.
+    """
+    if keep < 0:
+        raise CaptureError(f"keep must be 0 or more, not {keep}")
+
+    if not save_dir.is_dir():
+        return []
+
+    # TOLERANT OF THE OTHER SESSION THROUGHOUT, because two sessions sharing a
+    # save directory is the supported arrangement and pruning is not
+    # coordinated between them. A file can vanish between the listing, the
+    # sort's stat, the validation and the unlink - at each point "already
+    # gone" means the work is done, not that this prune failed. A vanished
+    # file's mtime sorts as oldest, which only ever makes it MORE likely to be
+    # aimed at, where the unlink finds nothing to do.
+    def _mtime(path: Path) -> float:
+        try:
+            return path.stat().st_mtime
+        except OSError:
+            return 0.0
+
+    pattern = capture_pattern(mod_name)
+    found = [entry for entry in save_dir.iterdir() if pattern.match(entry.name)]
+    found.sort(key=lambda p: (_mtime(p), p.name))
+
+    doomed = found if keep == 0 else found[:-keep]
+
+    # VALIDATED IN FULL BEFORE ANYTHING IS UNLINKED. Checking each file as it is
+    # deleted would leave a half-finished prune behind whenever one of them is
+    # refused - some files gone, an exception raised, and no record of where it
+    # stopped. Deciding first and acting second means a refusal costs nothing.
+    #
+    # `iterdir` yields symlinks, and one named like a capture passes the pattern
+    # while resolving somewhere else entirely. `contained` is what notices.
+    # `missing_ok` covers only absence - see its docstring - so the validation
+    # is exactly as strict about names and escapes as the read beside it.
+    targets = [
+        contained(save_dir, mod_name, path.name, missing_ok=True) for path in doomed
+    ]
+
+    for target in targets:
+        target.unlink(missing_ok=True)
+
+    return sorted(path.name for path in doomed)