backlog-digest 1.0.0__py3-none-any.whl

backlog_digest/__init__.py

@@ -0,0 +1,4 @@
+"""backlog-digest: розбір завалів збережених відео, статей, книг і постів."""
+
+__version__ = "1.0.0"
+APP_NAME = "backlog-digest"

backlog_digest/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

backlog_digest/autostart.py

@@ -0,0 +1,201 @@
+"""Автозапуск розкладу системним планувальником: щогодини й після входу в систему — `run-jobs`.
+
+Windows — Планувальник завдань (без вікна: pythonw); macOS — launchd (LaunchAgent користувача);
+Linux — таймер systemd користувача, а якщо systemd немає — cron. Права адміністратора не потрібні.
+Що й коли робити, вирішує вже сама програма (schedule.py), тож системне завдання однакове для всіх.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .paths import HOME_ENV
+
+NAME = "backlog-digest"
+LABEL = "io.github.backlog-digest"
+CRON_MARK = "# backlog-digest run-jobs"
+TIMEOUT = 60
+
+
+class AutostartError(Exception):
+    pass
+
+
+def command() -> list[str]:
+    """Чим запускати: той самий Python, що й зараз (venv чи uv tool), без вікна на Windows."""
+    exe = Path(sys.executable)
+    if sys.platform == "win32" and (exe.parent / "pythonw.exe").exists():
+        exe = exe.parent / "pythonw.exe"
+    cmd = [str(exe), "-m", "backlog_digest"]
+    home = os.environ.get(HOME_ENV)
+    if home:
+        cmd += ["--home", home]
+    return [*cmd, "run-jobs"]
+
+
+def _run(args: list[str], stdin: str | None = None) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(args, input=stdin, capture_output=True, text=True, encoding="utf-8", errors="replace",
+                              timeout=TIMEOUT)
+    except (OSError, subprocess.SubprocessError) as e:
+        raise AutostartError(str(e)) from e
+
+
+def _check(r: subprocess.CompletedProcess[str]) -> None:
+    if r.returncode != 0:
+        raise AutostartError((r.stderr or r.stdout).strip()[:500] or f"exit {r.returncode}")
+
+
+# ---------------------------------------------------------------- Windows
+
+def _ps(text: str) -> str:
+    return "'" + text.replace("'", "''") + "'"
+
+
+def windows_script(cmd: list[str]) -> str:
+    args = subprocess.list2cmdline(cmd[1:])
+    return f"""
+$action = New-ScheduledTaskAction -Execute {_ps(cmd[0])} -Argument {_ps(args)}
+$hourly = New-ScheduledTaskTrigger -Once -At (Get-Date).Date -RepetitionInterval (New-TimeSpan -Hours 1)
+$logon = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
+$logon.Delay = 'PT5M'
+$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -RunOnlyIfNetworkAvailable `
+  -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -MultipleInstances IgnoreNew `
+  -ExecutionTimeLimit (New-TimeSpan -Hours 4)
+Register-ScheduledTask -TaskName {_ps(NAME)} -Action $action -Trigger $hourly,$logon -Settings $settings `
+  -Description 'backlog-digest: run-jobs' -Force | Out-Null
+"""
+
+
+# ---------------------------------------------------------------- macOS
+
+def plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+
+
+def plist(cmd: list[str], log: Path) -> str:
+    def esc(s: str) -> str:
+        return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+    args = "\n".join(f"        <string>{esc(a)}</string>" for a in cmd)
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>{LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+{args}
+    </array>
+    <key>StartInterval</key>
+    <integer>3600</integer>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>{esc(str(log))}</string>
+    <key>StandardErrorPath</key>
+    <string>{esc(str(log))}</string>
+</dict>
+</plist>
+"""
+
+
+# ---------------------------------------------------------------- Linux
+
+def systemd_dir() -> Path:
+    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "systemd" / "user"
+
+
+def systemd_units(cmd: list[str]) -> dict[str, str]:
+    exec_line = " ".join(f'"{a}"' if " " in a else a for a in cmd)
+    return {
+        f"{NAME}.service": f"[Unit]\nDescription=backlog-digest: run-jobs\n\n[Service]\nType=oneshot\n"
+                           f"ExecStart={exec_line}\n",
+        f"{NAME}.timer": "[Unit]\nDescription=backlog-digest hourly\n\n[Timer]\nOnBootSec=5min\n"
+                         "OnUnitActiveSec=1h\nPersistent=true\n\n[Install]\nWantedBy=timers.target\n",
+    }
+
+
+def cron_line(cmd: list[str]) -> str:
+    return "0 * * * * " + " ".join(f"'{a}'" if " " in a else a for a in cmd) + f" >/dev/null 2>&1 {CRON_MARK}"
+
+
+def _crontab() -> str:
+    r = _run(["crontab", "-l"])
+    return r.stdout if r.returncode == 0 else ""   # «no crontab for user» — порожній
+
+
+def _has_systemd() -> bool:
+    return bool(shutil.which("systemctl")) and _run(["systemctl", "--user", "show-environment"]).returncode == 0
+
+
+# ---------------------------------------------------------------- спільне
+
+def installed() -> bool:
+    try:
+        if sys.platform == "win32":
+            return _run(["schtasks", "/Query", "/TN", NAME]).returncode == 0
+        if sys.platform == "darwin":
+            return plist_path().exists()
+        return (systemd_dir() / f"{NAME}.timer").exists() or (bool(shutil.which("crontab"))
+                                                               and CRON_MARK in _crontab())
+    except AutostartError:
+        return False
+
+
+def install(log: Path) -> str:
+    """Ставить (або оновлює) системне завдання. Повертає, куди саме: для повідомлення користувачу."""
+    cmd = command()
+    if sys.platform == "win32":
+        _check(_run(["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", windows_script(cmd)]))
+        return f"Task Scheduler: {NAME}"
+    if sys.platform == "darwin":
+        path = plist_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        log.parent.mkdir(parents=True, exist_ok=True)
+        _run(["launchctl", "unload", str(path)])      # старе — прибрати; помилку «не було» ігноруємо
+        path.write_text(plist(cmd, log), encoding="utf-8")
+        _check(_run(["launchctl", "load", "-w", str(path)]))
+        return str(path)
+    if _has_systemd():
+        folder = systemd_dir()
+        folder.mkdir(parents=True, exist_ok=True)
+        for name, text in systemd_units(cmd).items():
+            (folder / name).write_text(text, encoding="utf-8")
+        _check(_run(["systemctl", "--user", "daemon-reload"]))
+        _check(_run(["systemctl", "--user", "enable", "--now", f"{NAME}.timer"]))
+        return str(folder / f"{NAME}.timer")
+    if not shutil.which("crontab"):
+        raise AutostartError("systemd / cron")
+    lines = [ln for ln in _crontab().splitlines() if CRON_MARK not in ln]
+    _check(_run(["crontab", "-"], "\n".join([*lines, cron_line(cmd)]) + "\n"))
+    return "crontab"
+
+
+def remove() -> None:
+    if sys.platform == "win32":
+        r = _run(["schtasks", "/Delete", "/TN", NAME, "/F"])
+        if r.returncode != 0 and installed():
+            _check(r)
+        return
+    if sys.platform == "darwin":
+        path = plist_path()
+        if path.exists():
+            _run(["launchctl", "unload", "-w", str(path)])
+            path.unlink()
+        return
+    folder = systemd_dir()
+    if (folder / f"{NAME}.timer").exists():
+        _run(["systemctl", "--user", "disable", "--now", f"{NAME}.timer"])
+        for name in systemd_units([]):
+            (folder / name).unlink(missing_ok=True)
+        _run(["systemctl", "--user", "daemon-reload"])
+    if shutil.which("crontab"):
+        text = _crontab()
+        if CRON_MARK in text:
+            lines = [ln for ln in text.splitlines() if CRON_MARK not in ln]
+            _check(_run(["crontab", "-"], "\n".join(lines) + "\n" if lines else ""))

backlog_digest/cli.py

@@ -0,0 +1,256 @@
+"""Точка входу: backlog-digest / bdig [--lang uk|en|fr|es] [--home ТЕКА]
+[menu | setup | doctor | add | sync | process | fetch | summarize | export | shortcut | run-jobs | autostart]."""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__, config, db, doctor, i18n
+from .i18n import t
+from .paths import HOME_ENV, get_paths
+
+# команда → крок обробки: process — обидва кроки, fetch — лише тексти, summarize — лише конспекти
+STAGES = {"process": db.ALL, "fetch": db.FETCH, "summarize": db.SUMMARIZE}
+
+
+def main(argv: list[str] | None = None) -> int:
+    _setup_console()
+    argv = sys.argv[1:] if argv is None else argv
+    home = _option_from_argv(argv, "--home")
+    if home:   # так розклад передає теку програми: у системних завданнях змінні середовища не задати
+        os.environ[HOME_ENV] = home
+    paths = get_paths()
+
+    # Мову треба знати ще до розбору аргументів: від неї залежать тексти довідки.
+    cfg: dict[str, Any] | None
+    try:
+        cfg = config.load(paths)
+        cfg_error = None
+    except config.ConfigError as e:
+        cfg, cfg_error = None, e
+    i18n.set_language(_lang_from_argv(argv) or (cfg["general"]["ui_language"] if cfg else i18n.detect_language()))
+
+    args = build_parser().parse_args(argv)
+    if args.lang and cfg:
+        cfg["general"]["ui_language"] = args.lang   # лише на цей запуск, у файл не записуємо
+
+    if args.command == "doctor":
+        return doctor.run(paths, network=not args.offline)
+    if args.command == "shortcut":
+        from .menu import make_shortcut
+
+        return 0 if make_shortcut(paths) else 1
+
+    if cfg_error or cfg is None:
+        print(t("cli.config_error", error=cfg_error.message() if cfg_error else ""), file=sys.stderr)
+        print(t("cli.run_doctor"), file=sys.stderr)
+        return 2
+    if config.ensure(paths):
+        print(t("cli.config_created", path=str(paths.config_file)))
+        cfg = config.load(paths)
+        if args.lang:
+            cfg["general"]["ui_language"] = args.lang
+
+    try:
+        conn = db.connect(paths.db_file)
+    except db.DbError as e:
+        print(t("cli.db_error", error=str(e)), file=sys.stderr)
+        return 2
+    try:
+        return run_command(args, paths, cfg, conn)
+    except KeyboardInterrupt:
+        print(f"\n{t('menu.interrupted')}")
+        return 130
+    finally:
+        conn.close()
+
+
+def run_command(args: argparse.Namespace, paths: Any, cfg: dict[str, Any], conn: Any) -> int:
+    from . import pipeline, web
+    from .menu import Menu
+
+    if args.command == "add" and args.urls[0].lower() == "raindrop":
+        return _add_raindrop(conn, paths, args)
+    if args.command == "add":
+        # тека на диску — джерело «папка»; посилання не на YouTube або файл закладок — «статті»;
+        # інакше — посилання YouTube
+        local = Path(args.urls[0]).expanduser()
+        is_folder = len(args.urls) == 1 and local.is_absolute() and local.is_dir()
+        is_web = not is_folder and any((web.is_url(a) and not web.is_youtube(a)) or Path(a).expanduser().is_file()
+                                       for a in args.urls)
+        name = args.name or (local.name if is_folder else t("sources.web_default_name") if is_web else "YouTube")
+        if any(s["name"] == name for s in db.list_sources(conn)):
+            print(t("sources.name_taken", name=name), file=sys.stderr)
+            return 2
+        if is_folder:
+            sid = pipeline.add_folder_source(conn, name, str(local), args.folder or name)
+            print(t("sources.added_folder", name=name))
+        elif is_web:
+            urls = [a for a in args.urls if web.is_url(a)]
+            files = [str(Path(a).expanduser().resolve()) for a in args.urls if not web.is_url(a)]
+            sid = pipeline.add_web_source(conn, name, urls, files, args.folder or name, args.only)
+            print(t("sources.added_web", name=name))
+        else:
+            sid = pipeline.add_youtube_source(conn, name, args.urls, args.folder or name)
+            print(t("sources.added", name=name))
+        source = db.get_source(conn, sid)
+        if source and not args.no_sync:
+            print(t("sources.synced", new=pipeline.sync_source(conn, source)[0]))
+        return 0
+    if args.command == "sync":
+        print(t("sources.synced", new=pipeline.sync_all(conn)))
+        return 0
+    if args.command == "export":
+        return _export(conn, paths, cfg, args)
+    if args.command == "run-jobs":
+        from . import schedule
+
+        schedule.run_due(conn, cfg, paths, force=args.force, only=args.job or None)
+        return 0
+    if args.command == "autostart":
+        return _autostart(paths, args.action)
+    if args.command == "setup":
+        from . import wizard
+
+        wizard.run(Menu(paths, cfg, conn))
+        return 0
+    if args.command in STAGES:
+        limit = args.limit or cfg["limits"]["per_run"]
+        stats = pipeline.Processor(conn, cfg, paths).run(limit, args.source, STAGES[args.command])
+        return 3 if stats.stopped else 0
+    Menu(paths, cfg, conn).run(offer_wizard=True)
+    return 0
+
+
+def _add_raindrop(conn: Any, paths: Any, args: argparse.Namespace) -> int:
+    """bdig add raindrop [колекція ...] — усі закладки або лише названі колекції (з вкладеними)."""
+    from . import keys, pipeline, raindrop
+
+    token = keys.get_secret(raindrop.TOKEN, paths)
+    if not token:
+        print(t("raindrop.no_token"), file=sys.stderr)
+        return 2
+    wanted = args.urls[1:]
+    ids: list[int] = []
+    if wanted:
+        try:
+            cols = raindrop.collections(token)
+        except raindrop.RaindropError as e:
+            print(t("raindrop.failed", detail=str(e)), file=sys.stderr)
+            return 2
+        for title in wanted:
+            found = [c for c in cols if title.lower() in (c.title.lower(), c.title.rsplit("/", 1)[-1].lower())]
+            if not found:
+                print(t("raindrop.no_collection", name=title), file=sys.stderr)
+                return 2
+            ids += [c.id for c in found]
+    name = args.name or (wanted[0] if len(wanted) == 1 else "Raindrop")
+    if any(s["name"] == name for s in db.list_sources(conn)):
+        print(t("sources.name_taken", name=name), file=sys.stderr)
+        return 2
+    sid = pipeline.add_raindrop_source(conn, name, ids, args.folder or name)
+    print(t("sources.added_raindrop", name=name))
+    source = db.get_source(conn, sid)
+    if source and not args.no_sync:
+        print(t("sources.synced", new=pipeline.sync_source(conn, source)[0]))
+    return 0
+
+
+def _export(conn: Any, paths: Any, cfg: dict[str, Any], args: argparse.Namespace) -> int:
+    """bdig export [--root НАЗВА] — усі списки з конспектами в Raindrop (лише нове й змінене)."""
+    from . import export, keys, notes, raindrop
+
+    token = keys.get_secret(raindrop.TOKEN, paths)
+    if not token:
+        print(t("raindrop.no_token"), file=sys.stderr)
+        return 2
+    language = cfg["general"]["summary_language"]
+    lists = [(int(r["source_id"]), str(r["list_name"])) for r in db.done_lists(conn, language)]
+    root = args.root or cfg["raindrop"]["export_root"] or export.DEFAULT_ROOT
+    try:
+        stats = export.export(conn, token, lists, root, language, notes.load_labels(paths, language))
+    except raindrop.RaindropError as e:
+        print(t("raindrop.failed", detail=str(e)), file=sys.stderr)
+        return 1
+    print(t("export.done", created=stats.created, updated=stats.updated, unchanged=stats.unchanged,
+            collections=stats.collections))
+    return 0
+
+
+def _autostart(paths: Any, action: str) -> int:
+    from . import autostart
+
+    try:
+        if action == "on":
+            print(t("schedule.autostart_on", where=autostart.install(paths.data_dir / "logs" / "autostart.log")))
+        elif action == "off":
+            autostart.remove()
+            print(t("schedule.autostart_off"))
+        else:
+            print(t("schedule.autostart_yes") if autostart.installed() else t("schedule.autostart_no"))
+    except autostart.AutostartError as e:
+        print(t("schedule.autostart_failed", detail=str(e)), file=sys.stderr)
+        return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="backlog-digest", description=t("cli.description"))
+    parser.add_argument("--version", action="version", version=f"backlog-digest {__version__}")
+    parser.add_argument("--lang", choices=i18n.UI_LANGUAGES, help=t("cli.help_lang"))
+    parser.add_argument("--home", metavar="DIR", help=t("cli.help_home"))
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.add_parser("menu", help=t("cli.help_menu"))
+    p = sub.add_parser("doctor", help=t("cli.help_doctor"))
+    p.add_argument("--offline", action="store_true", help=t("cli.help_offline"))
+    p = sub.add_parser("add", help=t("cli.help_add"))
+    p.add_argument("urls", nargs="+", metavar="URL", help=t("cli.help_urls"))
+    p.add_argument("--name", help=t("cli.help_name"))
+    p.add_argument("--folder", help=t("cli.help_folder"))
+    p.add_argument("--no-sync", action="store_true", help=t("cli.help_no_sync"))
+    p.add_argument("--only", action="append", default=[], metavar="FOLDER", help=t("cli.help_only"))
+    sub.add_parser("sync", help=t("cli.help_sync"))
+    p = sub.add_parser("export", help=t("cli.help_export"))
+    p.add_argument("--root", metavar="NAME", help=t("cli.help_root"))
+    sub.add_parser("shortcut", help=t("cli.help_shortcut"))
+    sub.add_parser("setup", help=t("cli.help_setup"))
+    p = sub.add_parser("run-jobs", help=t("cli.help_run_jobs"))
+    p.add_argument("--force", action="store_true", help=t("cli.help_force"))
+    p.add_argument("--job", type=int, action="append", default=[], metavar="ID", help=t("cli.help_job"))
+    p = sub.add_parser("autostart", help=t("cli.help_autostart"))
+    p.add_argument("action", choices=("on", "off", "status"))
+    for command in STAGES:
+        p = sub.add_parser(command, help=t(f"cli.help_{command}"))
+        p.add_argument("--limit", type=int, help=t("cli.help_limit"))
+        p.add_argument("--source", type=int, metavar="ID", help=t("cli.help_source"))
+    return parser
+
+
+def _option_from_argv(argv: list[str], name: str) -> str | None:
+    for i, a in enumerate(argv):
+        if a.startswith(f"{name}="):
+            return a.split("=", 1)[1]
+        if a == name and i + 1 < len(argv):
+            return argv[i + 1]
+    return None
+
+
+def _lang_from_argv(argv: list[str]) -> str | None:
+    for i, a in enumerate(argv):
+        value = a.split("=", 1)[1] if a.startswith("--lang=") else (
+            argv[i + 1] if a == "--lang" and i + 1 < len(argv) else None)
+        if value in i18n.UI_LANGUAGES:
+            return value
+    return None
+
+
+def _setup_console() -> None:
+    # Коли вивід іде в файл чи конвеєр, Windows може взяти кодування без потрібних літер
+    # (напр. cp1251 без «é»). Краще знак питання замість літери, ніж падіння програми.
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure:
+            reconfigure(errors="replace")

backlog_digest/config.py

@@ -0,0 +1,179 @@
+"""Налаштування: config.toml у теці користувача (див. paths.py), поверх значень за замовчуванням.
+
+Формат TOML, а не YAML (як у прототипі): менше пасток з лапками й двокрапками,
+а читання вбудоване в Python (tomllib). Секрети тут не зберігаються — див. keys.py.
+"""
+from __future__ import annotations
+
+import copy
+import json
+import re
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from . import i18n
+from .paths import Paths
+
+OUTPUT_KINDS = ("obsidian", "markdown")
+
+DEFAULTS: dict[str, Any] = {
+    "general": {
+        "ui_language": "",        # мова інтерфейсу: uk / en / fr / es ("" — як у системі)
+        "summary_language": "",   # мова конспектів, незалежно від мови джерела ("" — як інтерфейс)
+    },
+    "output": {
+        "kind": "obsidian",       # obsidian / markdown
+        "path": "",               # тека сховища Obsidian або просто тека для Markdown
+    },
+    "limits": {
+        "per_run": 30,            # скільки елементів за один запуск
+        "per_day": 30,            # скільки субтитрів збирати за добу: YouTube рахує й добову кількість запитів
+    },
+    "youtube": {
+        "delay_min": 60,          # випадкова пауза між запитами субтитрів, с: YouTube обмежує IP за часті запити
+        "delay_max": 180,
+        "languages": [],          # бажані мови субтитрів ([] — англійська, потім мова конспектів)
+        "newest_first": False,    # обробляти спершу нові відео списку
+    },
+    "raindrop": {
+        "export_root": "Backlog digest",   # коренева колекція для експорту конспектів
+    },
+    "models": {
+        "order": ["gemini", "openrouter", "deepseek"],   # черга провайдерів: перший — основний
+        "thinking": "fast",       # «роздуми» моделі: fast / deep / auto
+        "temperature": 0.3,
+        "max_chars": 200000,      # довший текст обрізається
+        # Свій провайдер або свої моделі: [models.<назва>] base_url, key_env, models, json_mode
+    },
+}
+
+THINKING_MODES = ("fast", "deep", "auto")
+
+_LANG_CODE = re.compile(r"^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$")
+
+
+class ConfigError(Exception):
+    """Помилка в налаштуваннях. Текст — ключ перекладу з параметрами, перекладається під час показу."""
+
+    def __init__(self, key: str, **params: Any) -> None:
+        super().__init__(key)
+        self.key = key
+        self.params = params
+
+    def message(self) -> str:
+        return i18n.t(self.key, **self.params)
+
+
+def defaults() -> dict[str, Any]:
+    cfg = copy.deepcopy(DEFAULTS)
+    lang = i18n.detect_language()
+    cfg["general"]["ui_language"] = lang
+    cfg["general"]["summary_language"] = lang
+    return cfg
+
+
+def load(paths: Paths) -> dict[str, Any]:
+    """Читає config.toml і доповнює значеннями за замовчуванням. Файлу немає — лише значення за замовчуванням."""
+    cfg = defaults()
+    path = paths.config_file
+    if not path.exists():
+        return cfg
+    try:
+        user = tomllib.loads(path.read_text(encoding="utf-8-sig"))
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError("config.err_syntax", file=path.name, detail=str(e)) from e
+    except (OSError, UnicodeDecodeError) as e:
+        raise ConfigError("config.err_read", file=str(path), detail=str(e)) from e
+    _merge(cfg, user)
+    validate(cfg)
+    return cfg
+
+
+def _merge(base: dict[str, Any], user: dict[str, Any]) -> None:
+    for k, v in user.items():
+        if isinstance(v, dict) and isinstance(base.get(k), dict):
+            _merge(base[k], v)
+        else:
+            base[k] = v   # невідомі ключі зберігаємо — їх могла записати новіша версія програми
+
+
+def validate(cfg: dict[str, Any]) -> None:
+    g = cfg["general"]
+    if not g["ui_language"]:
+        g["ui_language"] = i18n.detect_language()
+    if g["ui_language"] not in i18n.UI_LANGUAGES:
+        raise ConfigError("config.err_ui_language", value=g["ui_language"],
+                          allowed=", ".join(i18n.UI_LANGUAGES))
+    if not g["summary_language"]:
+        g["summary_language"] = g["ui_language"]
+    if not isinstance(g["summary_language"], str) or not _LANG_CODE.match(g["summary_language"]):
+        raise ConfigError("config.err_summary_language", value=g["summary_language"])
+    if cfg["output"]["kind"] not in OUTPUT_KINDS:
+        raise ConfigError("config.err_output_kind", value=cfg["output"]["kind"],
+                          allowed=", ".join(OUTPUT_KINDS))
+    for section, name in (("limits", "per_run"), ("limits", "per_day"), ("models", "max_chars")):
+        v = cfg[section][name]
+        if not isinstance(v, int) or isinstance(v, bool) or v < 1:
+            raise ConfigError("config.err_positive_int", name=f"{section}.{name}", value=v)
+    yt = cfg["youtube"]
+    for name in ("delay_min", "delay_max"):
+        if not isinstance(yt[name], int | float) or isinstance(yt[name], bool) or yt[name] < 0:
+            raise ConfigError("config.err_positive_int", name=f"youtube.{name}", value=yt[name])
+    if yt["delay_max"] < yt["delay_min"]:
+        yt["delay_max"] = yt["delay_min"]
+    m = cfg["models"]
+    if m["thinking"] not in THINKING_MODES:
+        raise ConfigError("config.err_thinking", value=m["thinking"], allowed=", ".join(THINKING_MODES))
+    if not isinstance(m["order"], list) or not m["order"]:
+        raise ConfigError("config.err_models_order")
+
+
+def save(paths: Paths, cfg: dict[str, Any]) -> Path:
+    path = paths.config_file
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(dumps(cfg, header=i18n.t("config.file_header")), encoding="utf-8")
+    tmp.replace(path)   # атомарно: обірваний запис не зіпсує наявний файл
+    return path
+
+
+def ensure(paths: Paths) -> bool:
+    """Створює config.toml зі значеннями за замовчуванням, якщо його немає. True — щойно створено."""
+    if paths.config_file.exists():
+        return False
+    save(paths, defaults())
+    return True
+
+
+def dumps(cfg: dict[str, Any], header: str = "") -> str:
+    """Простий запис TOML: таблиці (й вкладені таблиці) зі скалярами та списками."""
+    lines = [f"# {line}" for line in header.splitlines()]
+    _dump_table(cfg, [], lines)
+    return "\n".join(lines) + "\n"
+
+
+def _dump_table(table: dict[str, Any], path: list[str], lines: list[str]) -> None:
+    for k, v in table.items():
+        if not isinstance(v, dict):
+            lines.append(f"{_key(k)} = {_value(v)}")
+    for k, v in table.items():
+        if isinstance(v, dict):
+            lines += ["", f"[{'.'.join(_key(p) for p in [*path, k])}]"]
+            _dump_table(v, [*path, k], lines)
+
+
+def _key(k: str) -> str:
+    return k if re.fullmatch(r"[A-Za-z0-9_-]+", k) else json.dumps(k, ensure_ascii=False)
+
+
+def _value(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, int | float):
+        return repr(v)
+    if isinstance(v, str):
+        return json.dumps(v, ensure_ascii=False)   # екранування JSON сумісне з рядками TOML
+    if isinstance(v, list):
+        return "[" + ", ".join(_value(x) for x in v) + "]"
+    raise TypeError(f"unsupported value type: {type(v).__name__}")