Skip to content

netresearch/matrix-skill / skills/matrix-administration

matrix-administration

Verified

Use when administering a Synapse / Matrix homeserver — list or snapshot all rooms, rate room health (public, unencrypted, orphaned), render a Graphviz map of the room/space tree, force-join users, promote room admins, harden rooms (add-to-space + restrict + encrypt), deactivate Matrix users (with GDPR erase), find biggest rooms by DB size, audit where a user is admin or member, replay join/leave timelines, or search unencrypted history. Trigger on any '/_synapse/admin', server-wide room operation, Matrix user offboarding, or anything requiring a homeserver-admin token — even without 'admin API' in the prompt. Companion to matrix-communication.

scripts/synapse-graph.py

View on GitHub
#!/usr/bin/env -S uv run --script
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""Render a snapshot of rooms as a Graphviz graph.

Reads ``rooms.json`` (produced by ``synapse-fetch-rooms.py``), writes
``rooms.dot`` (Graphviz source) and — if the ``dot`` binary is available —
``rooms.svg``.

Each room is a node coloured by its rating (green/orange/red).  Spaces are
drawn with a green/blue gradient when healthy.  Edges go from child rooms
to their parent space.

Usage:
    synapse-graph.py [--input rooms.json] [--dot rooms.dot] [--svg rooms.svg] \\
        [--language en|de] [--space '!ID:server' …] [--no-svg]
"""

from __future__ import annotations

import argparse
import json
import os
import shutil
import subprocess
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

from _lib import (
    Room,
    RoomRating,
    condense,
    format_rating,
    load_config,
    rate_room,
)

_COLORS = {
    "blue": "#2222ff",
    "bright_blue": "#7777ff",
    "red": "#ff2222",
    "bright_red": "#ff7777",
    "green": "#22cc22",
    "bright_green": "#77ff77",
    "gray": "#222222",
    "orange": "#ff8800",
    "bright_orange": "#ffaa22",
}


def _enc(value: str) -> str:
    """Escape a string for use inside a Graphviz DOT double-quoted literal.

    DOT treats backslash + character as an escape sequence (``\\n``,
    ``\\l``, ``\\r``, ``\\"``).  We escape backslashes first, then quotes,
    then newlines/CR — order matters so the backslash escape doesn't
    double-escape itself.
    """
    if value is None:
        return ""
    return (
        value.replace("\\", "\\\\")
        .replace('"', '\\"')
        .replace("\n", "\\n")
        .replace("\r", "\\r")
    )


def _join_policy_text(r: Room, rooms: dict[str, Room]) -> str:
    if isinstance(r.join_policy, tuple) and r.join_policy[0] == "in-space":
        names = [rooms[rid].name for rid in r.join_policy[1] if rid in rooms]
        return "members of " + ", ".join(names) if names else "members of (unknown)"
    if isinstance(r.join_policy, str):
        return r.join_policy
    return "unknown"


def node_label(r: Room, rooms: dict[str, Room]) -> str:
    """The DOT label of a room node, every room-supplied value escaped."""
    creator = (r.creator or "unknown").split(":")[0]
    return (
        f"{_icon(r)} {_enc(r.name)}\\n(v{_enc(str(r.version))}, "
        f"{_enc(_join_policy_text(r, rooms))}, by {_enc(creator)})"
    )


def _icon(r: Room) -> str:
    if r.join_policy == "public":
        return "🌐"
    if r.join_policy == "invite-only":
        return "🔒"
    return "🚀"


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    parser.add_argument("-i", "--input", default="rooms.json")
    parser.add_argument("--dot", default="rooms.dot")
    parser.add_argument("--svg", default="rooms.svg")
    parser.add_argument("-l", "--language", default=None, choices=["en", "de"])
    parser.add_argument(
        "-s",
        "--space",
        action="append",
        default=None,
        help="Space ID treated as 'home'. Repeatable.",
    )
    parser.add_argument(
        "--no-svg", action="store_true", help="Skip the dot → SVG step."
    )
    args = parser.parse_args()

    config = load_config(require_admin=False)
    language = args.language or os.environ.get("LANGUAGE", "en")
    if language not in ("en", "de"):
        language = "en"

    home_spaces: list[str] = list(args.space or [])
    if not home_spaces:
        cfg_home = config.get("home_space_ids") or []
        if isinstance(cfg_home, list):
            home_spaces.extend(cfg_home)
        if config.get("default_space_id"):
            home_spaces.append(config["default_space_id"])

    with open(args.input) as f:
        data = json.load(f)
    rooms = condense(data)

    lines: list[str] = ["digraph G {", '  graph [rankdir="LR"];']
    for r in rooms.values():
        if r.is_replaced:
            continue
        score, violations = rate_room(r, rooms, home_spaces, language)

        if score == RoomRating.SUCCESS:
            color = _COLORS["green"]
            fill = (
                f"{_COLORS['bright_green']}:{_COLORS['bright_blue']}"
                if r.is_space
                else _COLORS["bright_green"]
            )
        elif score == RoomRating.WARNING:
            color = _COLORS["orange"]
            fill = _COLORS["bright_orange"]
        else:
            color = _COLORS["red"]
            fill = _COLORS["bright_red"]

        label = node_label(r, rooms)
        tooltip = "\\n".join(format_rating(m) for m in violations)

        lines.append(
            f'  "{_enc(r.id)}" [label="{label}", style=filled, '
            f'color="{color}", fontcolor="black", fillcolor="{fill}", '
            f'tooltip="{_enc(tooltip)}", shape=rectangle, penwidth=3];'
        )
        for child_id in r.space_children:
            child = rooms.get(child_id)
            if not child or child.is_replaced:
                continue
            lines.append(
                f'  "{_enc(child_id)}" -> "{_enc(r.id)}" [label="space child"];'
            )

    lines.append("}")
    with open(args.dot, "w") as f:
        f.write("\n".join(lines) + "\n")

    if args.no_svg:
        print(f"Wrote {args.dot}")
        return 0

    if shutil.which("dot") is None:
        print(
            f"Wrote {args.dot}. Install Graphviz ('dot') to render the SVG, or pass --no-svg.",
            file=sys.stderr,
        )
        return 0

    try:
        subprocess.run(
            # Absolute paths start with "/", so a file name can never be
            # taken for a dot option such as -o or -T. Joined to the cwd
            # rather than abspath()'d, so ".." still resolves through
            # symlinks exactly as the open() that wrote the file did.
            [
                "dot",
                "-Tsvg",
                os.path.join(os.getcwd(), args.dot),
                "-o",
                os.path.join(os.getcwd(), args.svg),
            ],
            check=True,
        )
    except subprocess.CalledProcessError as e:
        print(f"dot failed: {e}", file=sys.stderr)
        return 1

    print(f"Wrote {args.dot} and {args.svg}")
    return 0


if __name__ == "__main__":
    sys.exit(main())
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall