Add a Commands tab to the staff panel

backend/src/api/luckperms_routes.py

@@ -16,10 +16,11 @@
 from src.api.patreon_routes import require_writer
 from src.api.request_body import read_json_body
 from src.auth import admin
-from src.luckperms import changes, mirror, views
+from src.luckperms import changes, commands, mirror, views
 
 SNAPSHOT_MAX_BYTES = 16 * 1024 * 1024
 RESULTS_MAX_BYTES = 4 * 1024 * 1024
+COMMANDS_MAX_BYTES = 8 * 1024 * 1024
 
 plugin_router = APIRouter(prefix="/luckperms/plugin", tags=["luckperms"], dependencies=[Depends(require_writer)])
 staff_router = APIRouter(prefix="/admin/luckperms", tags=["admin"])
@@ -34,6 +35,15 @@ async def put_snapshot(request: Request):
         raise HTTPException(400, detail=exc.code) from None
 
 
+@plugin_router.put("/commands")
+async def put_commands(request: Request):
+    payload = await read_json_body(request, COMMANDS_MAX_BYTES)
+    try:
+        return await run_in_threadpool(commands.store, payload)
+    except commands.CommandsError as exc:
+        raise HTTPException(400, detail=exc.code) from None
+
+
 class HashBody(BaseModel):
     hash: str = Field(..., max_length=128)
     revision: int = Field(..., gt=0)
@@ -82,6 +92,11 @@ def get_overview(request: Request, response: Response):
     return _read(request, response, views.overview)
 
 
+@staff_router.get("/commands")
+def get_commands(request: Request, response: Response):
+    return _read(request, response, commands.view)
+
+
 @staff_router.get("/groups/{name}")
 def get_group(name: str, request: Request, response: Response):
     return _read(request, response, lambda viewer: views.group_detail(viewer, name))

backend/src/luckperms/commands.py

@@ -0,0 +1,168 @@
+"""The server's commands and which LuckPerms groups may use them, for the Commands tab.
+
+TFMCWeb publishes the whole list; it replaces the stored one. Access is
+decided on the server from each command's own permission, so plugins may
+still refuse a command when it runs.
+"""
+from __future__ import annotations
+
+import json
+import time
+
+from src.skins.db import connect
+
+from . import mirror, nodes
+
+GROUPS_MAX = 200
+PLUGINS_MAX = 500
+COMMANDS_MAX = 10_000
+ALIASES_MAX = 64
+NAME_MAX = 64
+TEXT_MAX = 300
+PERMISSION_MAX = 2048
+# TFMCWeb resends at least every ten minutes.
+FRESH_SECONDS = 30 * 60
+KIND_ORDER = {"rank": 0, "staff": 1, "step": 2}
+
+
+class CommandsError(Exception):
+    def __init__(self, code: str):
+        super().__init__(code)
+        self.code = code
+
+
+def _text(raw, limit: int, *, required: bool = False) -> str | None:
+    if raw is None and not required:
+        return None
+    if not isinstance(raw, str) or not raw or len(raw) > limit:
+        raise CommandsError("bad_commands")
+    return raw
+
+
+def _command(raw, plugins: set[str], groups: int) -> dict:
+    if not isinstance(raw, dict):
+        raise CommandsError("bad_commands")
+    aliases = raw.get("aliases")
+    if not isinstance(aliases, list) or len(aliases) > ALIASES_MAX:
+        raise CommandsError("bad_commands")
+    plugin = _text(raw.get("plugin"), NAME_MAX, required=True)
+    if plugin not in plugins or not isinstance(raw.get("shadowed"), bool):
+        raise CommandsError("bad_commands")
+    permission = _text(raw.get("permission"), PERMISSION_MAX)
+    access = raw.get("access")
+    if permission is None:
+        if access is not None:
+            raise CommandsError("bad_commands")
+    elif not isinstance(access, str) or len(access) != groups or access.strip("yn"):
+        raise CommandsError("bad_commands")
+    return {
+        "plugin": plugin,
+        "name": _text(raw.get("name"), NAME_MAX, required=True),
+        "aliases": [_text(a, NAME_MAX, required=True) for a in aliases],
+        "description": _text(raw.get("description"), TEXT_MAX),
+        "usage": _text(raw.get("usage"), TEXT_MAX),
+        "permission": permission,
+        "shadowed": raw["shadowed"],
+        "access": access,
+    }
+
+
+def store(payload) -> dict:
+    if not isinstance(payload, dict):
+        raise CommandsError("bad_commands")
+    groups, plugins, commands = payload.get("groups"), payload.get("plugins"), payload.get("commands")
+    if (not isinstance(groups, list) or not isinstance(plugins, list) or not isinstance(commands, list)
+            or len(groups) > GROUPS_MAX or len(plugins) > PLUGINS_MAX or len(commands) > COMMANDS_MAX):
+        raise CommandsError("bad_commands")
+    group_names = [_text(g, NAME_MAX * 2, required=True).lower() for g in groups]
+    plugin_rows = []
+    for raw in plugins:
+        if not isinstance(raw, dict):
+            raise CommandsError("bad_commands")
+        plugin_rows.append({"name": _text(raw.get("name"), NAME_MAX, required=True),
+                            "version": _text(raw.get("version"), NAME_MAX)})
+    names = {p["name"] for p in plugin_rows}
+    command_rows = [_command(raw, names, len(group_names)) for raw in commands]
+    generated_at = payload.get("generated_at")
+    if not isinstance(generated_at, int) or isinstance(generated_at, bool) or generated_at <= 0:
+        raise CommandsError("bad_commands")
+    server = _text(payload.get("server"), 32, required=True)
+    snapshot_hash = _text(payload.get("hash"), 128)
+    body = json.dumps({"groups": group_names, "plugins": plugin_rows, "commands": command_rows},
+                      separators=(",", ":"))
+    with connect() as conn:
+        conn.execute(
+            """
+            INSERT INTO lp_commands (id, server, hash, generated_at, received_at, payload)
+            VALUES (1, ?, ?, ?, ?, ?)
+            ON CONFLICT(id) DO UPDATE SET server = excluded.server, hash = excluded.hash,
+                generated_at = excluded.generated_at, received_at = excluded.received_at,
+                payload = excluded.payload
+            """,
+            (server, snapshot_hash, generated_at, mirror._iso(), body),
+        )
+        conn.commit()
+    return {"ok": True, "commands": len(command_rows)}
+
+
+def _kinds(tracks: list[dict]) -> dict[str, tuple[str, str]]:
+    """A track's last group is a staff rank; the groups before it are its steps."""
+    out: dict[str, tuple[str, str]] = {}
+    for track in tracks:
+        if not track["groups"]:
+            continue
+        *steps, last = track["groups"]
+        out[last] = ("staff", track["name"])
+        for step in steps:
+            out.setdefault(step, ("step", track["name"]))
+    return out
+
+
+def view(viewer: dict) -> dict:
+    now = int(time.time())
+    with connect() as conn:
+        row = conn.execute(
+            "SELECT server, generated_at, received_at, payload FROM lp_commands WHERE id = 1").fetchone()
+        if row is None:
+            return {"status": None, "groups": [], "plugins": []}
+        groups = mirror.load_groups(conn)
+        counts = mirror.group_counts(conn)
+        tracks = mirror.load_tracks(conn)
+    data = json.loads(row["payload"])
+    kinds = _kinds(tracks)
+    listed = []
+    for index, name in enumerate(data["groups"]):
+        group = groups.get(name, {"name": name, "display_name": None, "weight": None, "nodes": []})
+        kind, track = kinds.get(name, ("rank", None))
+        listed.append((index, {
+            "name": name,
+            "display_name": group["display_name"],
+            "weight": group["weight"],
+            "members": counts.get(name, 0),
+            "kind": kind,
+            "track": track,
+            "parents": mirror.parents(group, now),
+            "nodes": [n for n in group["nodes"] if nodes.kind(n["key"]) == "permission"],
+        }))
+    listed.sort(key=lambda item: (KIND_ORDER[item[1]["kind"]], item[1]["weight"] or 0, item[1]["name"]))
+    order = [index for index, _ in listed]
+    plugins: dict[str, dict] = {p["name"]: {**p, "commands": []} for p in data["plugins"]}
+    for command in data["commands"]:
+        access = command["access"]
+        plugins[command["plugin"]]["commands"].append({
+            **{k: v for k, v in command.items() if k != "plugin"},
+            "access": None if access is None else "".join(access[i] for i in order),
+        })
+    for plugin in plugins.values():
+        plugin["commands"].sort(key=lambda c: (c["name"], c["shadowed"]))
+    received = mirror._age(row["received_at"], time.time())
+    return {
+        "status": {
+            "server": row["server"],
+            "generated_at": row["generated_at"],
+            "received_at": row["received_at"],
+            "fresh": received is not None and received <= FRESH_SECONDS,
+        },
+        "groups": [group for _, group in listed],
+        "plugins": sorted((p for p in plugins.values() if p["commands"]), key=lambda p: p["name"].lower()),
+    }

backend/src/luckperms/test_commands.py

@@ -0,0 +1,121 @@
+import pytest
+
+from src.luckperms import commands
+from src.luckperms.test_luckperms import PLUGIN, SECONDARY, app, bridge, client, env, staff  # noqa: F401
+
+
+def command(name, plugin="Essentials", permission=None, access=None, **extra):
+    return {"plugin": plugin, "name": name, "aliases": extra.get("aliases", []),
+            "description": extra.get("description"), "usage": extra.get("usage"), "permission": permission,
+            "shadowed": extra.get("shadowed", False), "access": access}
+
+
+def catalogue(**overrides):
+    # Groups in the plugin's (alphabetical) order; access follows it.
+    payload = {
+        "server": "main",
+        "generated_at": 1792076432,
+        "hash": "c1",
+        "groups": ["commoner", "default", "helper", "helper_inactive", "helper_player", "noble", "staff"],
+        "plugins": [{"name": "Essentials", "version": "2.22.0"}, {"name": "LibsDisguises", "version": None},
+                    {"name": "Unused", "version": "1"}],
+        "commands": [
+            command("me", permission="essentials.me", access="yyyyyyy", aliases=["eme"],
+                    description="Describes an action."),
+            command("kick", permission="essentials.kick", access="nnynnny"),
+            command("disguise", plugin="LibsDisguises", permission="libsdisguises.seecmd.disguise",
+                    access="yyyyyyy", usage="/disguise <type>"),
+            command("me", plugin="LibsDisguises", shadowed=True),
+        ],
+    }
+    payload.update(overrides)
+    return payload
+
+
+def test_plugin_route_needs_the_primary_key(app):
+    plugin = client(app)
+    assert plugin.put("/luckperms/plugin/commands", json=catalogue()).status_code == 401
+    assert plugin.put("/luckperms/plugin/commands", headers=SECONDARY, json=catalogue()).status_code == 403
+
+
+@pytest.mark.parametrize("change", [
+    {"groups": "x"},
+    {"groups": [""]},
+    {"plugins": ["x"]},
+    {"commands": [command("me", plugin="Nobody")]},
+    {"commands": [command("me", permission="essentials.me", access="yy")]},
+    {"commands": [command("me", permission="essentials.me", access="yyyyyyx")]},
+    {"commands": [command("me", access="yyyyyyy")]},
+    {"commands": [{**command("me"), "shadowed": "no"}]},
+    {"commands": [{**command("me"), "aliases": "eme"}]},
+    {"commands": [command("x" * 65)]},
+    {"commands": ["me"]},
+    {"generated_at": True},
+    {"server": None},
+])
+def test_malformed_lists_are_refused(app, change):
+    response = client(app).put("/luckperms/plugin/commands", headers=PLUGIN, json=catalogue(**change))
+    assert response.status_code == 400 and response.json()["detail"] == "bad_commands"
+    assert client(app).put("/luckperms/plugin/commands", headers=PLUGIN, json=[1]).status_code == 400
+
+
+def test_staff_see_commands_with_groups_in_rank_order(app, bridge, staff):
+    mod = client(app, staff["mod"])
+    assert mod.get("/admin/luckperms/commands").json() == {"status": None, "groups": [], "plugins": []}
+    assert bridge.put("/luckperms/plugin/commands", headers=PLUGIN, json=catalogue()).json() == {
+        "ok": True, "commands": 4}
+
+    data = mod.get("/admin/luckperms/commands").json()
+
+    assert data["status"]["server"] == "main" and data["status"]["generated_at"] == 1792076432
+    assert data["status"]["fresh"] is True
+    assert [(g["name"], g["kind"], g["track"]) for g in data["groups"]] == [
+        ("default", "rank", None), ("commoner", "rank", None), ("noble", "rank", None),
+        ("helper", "staff", "helper"), ("staff", "staff", "staff"),
+        ("helper_player", "step", "helper"), ("helper_inactive", "step", "helper"),
+    ]
+    helper = data["groups"][3]
+    assert helper["parents"] == ["helper_inactive"] and helper["members"] == 0
+    assert [n["key"] for n in helper["nodes"]] == ["essentials.kick"]
+    staff_group = data["groups"][4]
+    assert staff_group["members"] == 2 and staff_group["weight"] == 200
+    assert [p["name"] for p in data["plugins"]] == ["Essentials", "LibsDisguises"]
+    essentials = data["plugins"][0]
+    assert essentials["version"] == "2.22.0"
+    assert [c["name"] for c in essentials["commands"]] == ["kick", "me"]
+    # default, commoner, noble, helper, staff, helper_player, helper_inactive
+    assert essentials["commands"][0]["access"] == "nnnyynn"
+    assert essentials["commands"][1] == {"name": "me", "aliases": ["eme"], "description": "Describes an action.",
+                                         "usage": None, "permission": "essentials.me", "shadowed": False,
+                                         "access": "yyyyyyy"}
+    shadowed = data["plugins"][1]["commands"][1]
+    assert shadowed["shadowed"] is True and shadowed["access"] is None
+
+
+def test_groups_missing_from_the_mirror_still_show(app, staff, env):
+    plugin = client(app)
+    payload = catalogue(groups=["ghost"], commands=[command("me", permission="essentials.me", access="y")])
+    assert plugin.put("/luckperms/plugin/commands", headers=PLUGIN, json=payload).status_code == 200
+    data = client(app, staff["mod"]).get("/admin/luckperms/commands").json()
+    assert data["groups"] == [{"name": "ghost", "display_name": None, "weight": None, "members": 0, "kind": "rank",
+                               "track": None, "parents": [], "nodes": []}]
+
+
+def test_old_lists_are_marked_stale(app, staff, env):
+    assert client(app).put("/luckperms/plugin/commands", headers=PLUGIN, json=catalogue()).status_code == 200
+    with env.connect() as conn:
+        conn.execute("UPDATE lp_commands SET received_at = '2026-01-01T00:00:00Z'")
+        conn.commit()
+    assert client(app, staff["mod"]).get("/admin/luckperms/commands").json()["status"]["fresh"] is False
+
+
+def test_players_cannot_read_commands(app, env):
+    from src.luckperms.test_luckperms import account
+    player = account(env, "pat")
+    assert client(app, player).get("/admin/luckperms/commands").status_code == 403
+    assert client(app).get("/admin/luckperms/commands").status_code == 401
+
+
+def test_empty_tracks_are_ignored():
+    assert commands._kinds([{"name": "empty", "groups": []}, {"name": "t", "groups": ["a", "b"]}]) == {
+        "b": ("staff", "t"), "a": ("step", "t")}

backend/src/skins/schema.sql

@@ -851,6 +851,17 @@ CREATE TABLE IF NOT EXISTS lp_user_nodes (
 CREATE INDEX IF NOT EXISTS idx_lp_user_nodes_uuid ON lp_user_nodes(uuid);
 CREATE INDEX IF NOT EXISTS idx_lp_user_nodes_key ON lp_user_nodes(key);
 
+-- The server's commands and each group's access, as TFMCWeb last published
+-- them for the Commands tab; see src/luckperms/commands.py.
+CREATE TABLE IF NOT EXISTS lp_commands (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    server TEXT,
+    hash TEXT,
+    generated_at INTEGER,
+    received_at TEXT,
+    payload TEXT NOT NULL
+);
+
 -- Changes staff queued for the bridge. Rows are kept as the change history.
 CREATE TABLE IF NOT EXISTS lp_changes (
     id INTEGER PRIMARY KEY AUTOINCREMENT,

frontend/app/admin/commands/page.tsx

@@ -0,0 +1,18 @@
+import AdminColumn from "../../components/admin/AdminColumn";
+import CommandsOverview from "../../components/admin/commands/CommandsOverview";
+import { parseCommandsState } from "@/lib/admin/commands";
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+
+export default async function AdminCommandsPage({ searchParams }: { searchParams: SearchParams }) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(await searchParams)) {
+    const first = Array.isArray(value) ? value[0] : value;
+    if (first !== undefined) params.set(key, first);
+  }
+  return (
+    <AdminColumn>
+      <CommandsOverview initialState={parseCommandsState(params)} />
+    </AdminColumn>
+  );
+}

frontend/app/components/admin/AdminNav.test.tsx

@@ -17,6 +17,7 @@ it("puts each staff path under its tab, sub-pages included", () => {
   expect(adminSection("/admin/movement")).toBe("movement");
   expect(adminSection("/admin/rail")).toBe("rail");
   expect(adminSection("/admin/ranks/groups/staff")).toBe("ranks");
+  expect(adminSection("/admin/commands")).toBe("commands");
   expect(adminSection("/admin/precedent")).toBe("precedent");
   expect(adminSection("/admin/codes")).toBe("codes");
   expect(adminSection("/admin/servers")).toBe("servers");
@@ -31,3 +32,12 @@ it("marks the tab for the current path", () => {
   expect(screen.getByRole("link", { name: "Ranks" }).getAttribute("aria-current")).toBe("page");
   expect(screen.getByRole("link", { name: "Accounts" }).getAttribute("aria-current")).toBeNull();
 });
+
+it("places Commands after Ranks and marks it current", () => {
+  pathname.current = "/admin/commands";
+  render(<AdminNav />);
+  const links = screen.getAllByRole("link");
+  const ranksIndex = links.findIndex((link) => link.textContent === "Ranks");
+  expect(links[ranksIndex + 1].textContent).toBe("Commands");
+  expect(links[ranksIndex + 1].getAttribute("aria-current")).toBe("page");
+});

frontend/app/components/admin/AdminNav.tsx

@@ -10,6 +10,7 @@ const LINKS = [
   { href: "/admin/movement", label: "Movement", key: "movement" },
   { href: "/admin/rail", label: "Rail", key: "rail" },
   { href: "/admin/ranks", label: "Ranks", key: "ranks" },
+  { href: "/admin/commands", label: "Commands", key: "commands" },
   { href: "/admin/precedent", label: "Precedent", key: "precedent" },
   { href: "/admin/codes", label: "Codes", key: "codes" },
   { href: "/admin/servers", label: "Servers", key: "servers" },