diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md new file mode 100644 index 0000000..5f8d1dc --- /dev/null +++ b/docs/COMMANDS.md @@ -0,0 +1,44 @@ +# Справочник команд + +Файл создан автоматически из `ops/bots/commands.yaml`. +**Правьте справочник, а не этот файл.** + +## ADM — Управление службами и состояние инфраструктуры +Отвечает на команды о состоянии и выполняет перезапуски. + +| Команда | Что делает | Доступ | Состояние | +|---|---|---|---| +| `/status` | Показывает состояние хостов и служб с ответами проверок. | все | готово | +| `/issues` | Список открытых задач Gitea с метками важности. | все | готово | +| `/runbook <сервис>` | Показывает инструкцию по обслуживанию указанного сервиса. | все | готово | +| `/restart <сервис>` | Перезапускает службу через службу восстановления. | админ | готово | + +## WORK — Обновления и рабочие задачи +Показывает очередь обновлений и принимает решения по ним. + +| Команда | Что делает | Доступ | Состояние | +|---|---|---|---| +| `/queue` | Показывает очередь обновлений с номерами заявок. | все | готовится | +| `/approve <номер>` | Ставит заявку в работу — обновление будет выполнено. | админ | готовится | +| `/reject <номер>` | Отклоняет заявку — обновление выполнено не будет. | админ | готовится | +| `/update <служба>` | Немедленно ставит обновление службы в очередь. | админ | готовится | + +## AUTH — Доступ и регистрация +Обслуживает заявки на доступ к сервисам. + +| Команда | Что делает | Доступ | Состояние | +|---|---|---|---| +| `/requests` | Показывает необработанные заявки на регистрацию. | админ | готовится | +| `/approve-user <почта>` | Даёт доступ указанному пользователю и создаёт учётную запись. | админ | готовится | +| `/deny-user <почта>` | Отклоняет заявку на доступ. | админ | готовится | + +## MEDIA — Медиа-службы +Состояние и управление медиасервисами. + +| Команда | Что делает | Доступ | Состояние | +|---|---|---|---| +| `/media` | Показывает состояние медиасервисов и их очереди загрузок. | все | готовится | + +## Общие команды + +- `/help [команда]` — Показывает команды этого бота. Можно указать команду подробнее. diff --git a/ops/bots/commands.yaml b/ops/bots/commands.yaml new file mode 100644 index 0000000..9dab577 --- /dev/null +++ b/ops/bots/commands.yaml @@ -0,0 +1,189 @@ +# ============================================================ +# Справочник команд buryan-hub — ЕДИНСТВЕННЫЙ ИСТОЧНИК ПРАВДЫ +# ============================================================ +# Из этого файла генерируется: +# * ответ /help в каждом боте (только его команды); +# * docs/COMMANDS.md в репозитории; +# * закреплённое сообщение в комнате Matrix. +# +# ДОБАВИТЬ КОМАНДУ = ДОБАВИТЬ ЗАПИСЬ СЮДА. Помощь обновится сама. +# +# Поля: +# command — как вызывается, без слэша +# bot — какому боту принадлежит: adm | work | alert | auth | media +# title — короткое название +# description — что делает, одним предложением +# usage — как вызывать +# examples — примеры (показываются в /help) +# access — admin | user (кто может вызывать) +# aliases — другие написания +# status — ready | planned (planned показывается серым, но видно) + +bots: + adm: + name: ADM + purpose: Управление службами и состояние инфраструктуры + about: Отвечает на команды о состоянии и выполняет перезапуски. + + work: + name: WORK + purpose: Обновления и рабочие задачи + about: Показывает очередь обновлений и принимает решения по ним. + + alert: + name: ALERT + purpose: Тревоги инфраструктуры + about: Только сообщает о проблемах и восстановлении. Команд не принимает. + + auth: + name: AUTH + purpose: Доступ и регистрация + about: Обслуживает заявки на доступ к сервисам. + + media: + name: MEDIA + purpose: Медиа-службы + about: Состояние и управление медиасервисами. + +commands: + + # ─── ADM: состояние и управление ─────────────────────────── + - command: status + bot: adm + title: Состояние служб + description: Показывает состояние хостов и служб с ответами проверок. + usage: /status + examples: + - /status + access: user + aliases: ["!status"] + status: ready + + - command: issues + bot: adm + title: Открытые задачи + description: Список открытых задач Gitea с метками важности. + usage: /issues + examples: + - /issues + access: user + aliases: ["!issues"] + status: ready + + - command: runbook + bot: adm + title: Ранбук сервиса + description: Показывает инструкцию по обслуживанию указанного сервиса. + usage: /runbook <сервис> + examples: + - /runbook radarr + - /runbook n8n + access: user + aliases: ["!runbook"] + status: ready + + - command: restart + bot: adm + title: Перезапуск службы + description: Перезапускает службу через службу восстановления. + usage: /restart <сервис> + examples: + - /restart radarr + access: admin + aliases: ["!restart"] + status: ready + + # ─── WORK: обновления ────────────────────────────────────── + - command: queue + bot: work + title: Очередь обновлений + description: Показывает очередь обновлений с номерами заявок. + usage: /queue + examples: + - /queue + access: user + status: planned + + - command: approve + bot: work + title: Одобрить обновление + description: Ставит заявку в работу — обновление будет выполнено. + usage: /approve <номер> + examples: + - /approve 17 + access: admin + status: planned + + - command: reject + bot: work + title: Отклонить обновление + description: Отклоняет заявку — обновление выполнено не будет. + usage: /reject <номер> + examples: + - /reject 17 + access: admin + status: planned + + - command: update + bot: work + title: Обновить службу сейчас + description: Немедленно ставит обновление службы в очередь. + usage: /update <служба> + examples: + - /update prowlarr + access: admin + status: planned + + # ─── AUTH: доступ ────────────────────────────────────────── + - command: requests + bot: auth + title: Заявки на доступ + description: Показывает необработанные заявки на регистрацию. + usage: /requests + examples: + - /requests + access: admin + status: planned + + - command: approve-user + bot: auth + title: Одобрить заявку + description: Даёт доступ указанному пользователю и создаёт учётную запись. + usage: /approve-user <почта> + examples: + - /approve-user user@example.com + access: admin + status: planned + + - command: deny-user + bot: auth + title: Отклонить заявку + description: Отклоняет заявку на доступ. + usage: /deny-user <почта> + examples: + - /deny-user user@example.com + access: admin + status: planned + + # ─── MEDIA: медиасервисы ─────────────────────────────────── + - command: media + bot: media + title: Состояние медиасервисов + description: Показывает состояние медиасервисов и их очереди загрузок. + usage: /media + examples: + - /media + access: user + status: planned + + # ─── Общие для всех ботов ────────────────────────────────── + - command: help + bot: all + title: Справка + description: Показывает команды этого бота. Можно указать команду подробнее. + usage: /help [команда] + examples: + - /help + - /help restart + access: user + status: ready diff --git a/ops/bots/gen_help.py b/ops/bots/gen_help.py new file mode 100644 index 0000000..a982bde --- /dev/null +++ b/ops/bots/gen_help.py @@ -0,0 +1,251 @@ +#!/usr/bin/env python3 +"""Генератор справки по командам. + +Из единственного источника правды (commands.yaml) делает: + * ответ /help для каждого бота — только его команды; + * docs/COMMANDS.md — общий справочник в репозитории; + * подсказку при опечатке. + +Зачем: команды не должны жить в голове и не должны быть зашиты +в код. Добавить команду = добавить запись в commands.yaml, +а справка обновится сама. + +Использование: + python3 gen_help.py — показать справку всем ботам + python3 gen_help.py --bot adm — справка одного бота + python3 gen_help.py --command restart — подробно про команду + python3 gen_help.py --markdown FILE — записать общий справочник + python3 gen_help.py --suggest statsu — подсказать похожую команду +""" +from __future__ import annotations + +import argparse +import difflib +import os +import sys + +try: + import yaml +except ImportError: # запасной разбор, если PyYAML не установлен + yaml = None + +CATALOG = os.getenv("COMMANDS_FILE", + os.path.join(os.path.dirname(os.path.abspath(__file__)), + "commands.yaml")) + + +def load(path: str = CATALOG) -> dict: + """Читает справочник. Если PyYAML нет — разбирает встроенным способом.""" + with open(path, encoding="utf-8") as fh: + text = fh.read() + if yaml is not None: + return yaml.safe_load(text) + return _simple_parse(text) + + +def _simple_parse(text: str) -> dict: + """Минимальный разбор YAML для нашего формата — без внешних зависимостей. + + Понимает списки словарей с простыми значениями и списками строк. + Нужен, чтобы справка работала даже там, где PyYAML не установлен. + """ + data: dict = {"bots": {}, "commands": []} + section = None + item: dict | None = None + list_key = None + bot_key = None + bot_item: dict | None = None + + for raw in text.split("\n"): + line = raw.rstrip() + if not line or line.lstrip().startswith("#"): + continue + stripped = line.strip() + + if line.startswith("bots:") and not line.startswith(" "): + section, item, bot_item = "bots", None, None + continue + if line.startswith("commands:") and not line.startswith(" "): + section, item, bot_item = "commands", None, None + continue + + if section == "bots": + if line.startswith(" ") and not line.startswith(" ") and stripped.endswith(":"): + bot_key = stripped[:-1] + bot_item = {} + data["bots"][bot_key] = bot_item + continue + if bot_item is not None and ":" in stripped: + k, v = stripped.split(":", 1) + bot_item[k.strip()] = v.strip() + continue + continue + + if section == "commands": + if stripped.startswith("- "): + item = {} + data["commands"].append(item) + list_key = None + rest = stripped[2:] + if ":" in rest: + k, v = rest.split(":", 1) + item[k.strip()] = v.strip() + continue + if item is None: + continue + if stripped.endswith(":") and not stripped.startswith("-"): + list_key = stripped[:-1] + item[list_key] = [] + continue + if stripped.startswith("- ") and list_key: + item[list_key].append(stripped[2:].strip().strip('"\'')) + continue + if ":" in stripped: + k, v = stripped.split(":", 1) + item[k.strip()] = v.strip().strip('"\'') + list_key = None + return data + + +def commands_for(data: dict, bot: str) -> list[dict]: + """Команды бота: его собственные плюс общие (bot: all).""" + out = [] + for cmd in data.get("commands", []): + if cmd.get("bot") in (bot, "all"): + out.append(cmd) + return out + + +def help_text(data: dict, bot: str) -> str: + """Справка для бота. Коротко: название, вызов, описание.""" + info = data.get("bots", {}).get(bot, {}) + lines = [] + if info.get("name"): + lines.append(f"{info['name']} — {info.get('purpose', '')}") + lines.append("") + + ready = [c for c in commands_for(data, bot) if c.get("status") != "planned"] + planned = [c for c in commands_for(data, bot) if c.get("status") == "planned"] + + lines.append("Доступные команды:") + for cmd in ready: + access = " (только админ)" if cmd.get("access") == "admin" else "" + lines.append(f"/{cmd['command']} — {cmd.get('description', '')}{access}") + + if planned: + lines.append("") + lines.append("Готовятся:") + for cmd in planned: + lines.append(f"/{cmd['command']} — {cmd.get('description', '')}") + + lines.append("") + lines.append("Подробнее о команде: /help <команда>") + return "\n".join(lines) + + +def command_help(data: dict, name: str) -> str | None: + """Подробная справка по одной команде.""" + name = name.lstrip("/!").strip() + for cmd in data.get("commands", []): + if cmd.get("command") == name or name in (cmd.get("aliases") or []): + lines = [f"/{cmd['command']} — {cmd.get('title', '')}"] + lines.append(cmd.get("description", "")) + lines.append("") + lines.append(f"Вызов: {cmd.get('usage', '/' + cmd['command'])}") + if cmd.get("examples"): + lines.append("Примеры:") + for ex in cmd["examples"]: + lines.append(f" {ex}") + if cmd.get("aliases"): + lines.append(f"Варианты: {', '.join(cmd['aliases'])}") + if cmd.get("access") == "admin": + lines.append("Доступ: только администратор") + if cmd.get("status") == "planned": + lines.append("Состояние: готовится, пока не работает") + if cmd.get("bot") and cmd["bot"] != "all": + lines.append(f"Бот: {data.get('bots', {}).get(cmd['bot'], {}).get('name', cmd['bot'])}") + return "\n".join(lines) + return None + + +def suggest(data: dict, wrong: str | None) -> str | None: + """Подсказка при опечатке: «возможно, вы имели в виду».""" + if not wrong: + return None + names = [c["command"] for c in data.get("commands", [])] + close = difflib.get_close_matches(wrong.lstrip("/!").strip(), names, n=1, cutoff=0.6) + if close: + return f"Команда не распознана. Возможно, вы имели в виду /{close[0]}? Список: /help" + return "Команда не распознана. Список команд: /help" + + +def markdown(data: dict) -> str: + """Общий справочник для репозитория.""" + lines = ["# Справочник команд", "", + "Файл создан автоматически из `ops/bots/commands.yaml`.", + "**Правьте справочник, а не этот файл.**", ""] + + for bot_key, info in data.get("bots", {}).items(): + cmds = [c for c in commands_for(data, bot_key) if c.get("bot") == bot_key] + if not cmds: + continue + lines.append(f"## {info.get('name', bot_key)} — {info.get('purpose', '')}") + if info.get("about"): + lines.append(info["about"]) + lines.append("") + lines.append("| Команда | Что делает | Доступ | Состояние |") + lines.append("|---|---|---|---|") + for cmd in cmds: + access = "админ" if cmd.get("access") == "admin" else "все" + state = "готово" if cmd.get("status") != "planned" else "готовится" + lines.append(f"| `{cmd.get('usage', '/' + cmd['command'])}` | " + f"{cmd.get('description', '')} | {access} | {state} |") + lines.append("") + + lines.append("## Общие команды") + lines.append("") + for cmd in data.get("commands", []): + if cmd.get("bot") == "all": + lines.append(f"- `{cmd.get('usage')}` — {cmd.get('description', '')}") + lines.append("") + return "\n".join(lines) + + +def main() -> int: + ap = argparse.ArgumentParser(description="Генератор справки по командам") + ap.add_argument("--bot", help="показать справку одного бота") + ap.add_argument("--command", help="подробно про команду") + ap.add_argument("--suggest", help="подсказать похожую команду") + ap.add_argument("--markdown", metavar="FILE", help="записать общий справочник") + ap.add_argument("--catalog", default=CATALOG, help="путь к справочнику") + args = ap.parse_args() + + if not os.path.exists(args.catalog): + print(f"справочник не найден: {args.catalog}", file=sys.stderr) + return 1 + data = load(args.catalog) + + if args.command: + print(command_help(data, args.command) or "Команда не найдена") + return 0 + if args.suggest: + print(suggest(data, args.suggest) or "") + return 0 + if args.markdown: + with open(args.markdown, "w", encoding="utf-8") as fh: + fh.write(markdown(data)) + print(f"записан справочник: {args.markdown}") + return 0 + if args.bot: + print(help_text(data, args.bot)) + return 0 + + for bot in data.get("bots", {}): + print("=" * 60) + print(help_text(data, bot)) + print() + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())