release: v0.5.1

README.md

@@ -409,7 +409,7 @@ Example output:
 
 ```
   ╔══════════════════════════════════════════════════════════╗
-  ║                 opencode-db — справка                   ║
+  ║                 opencode-db — справка                    ║
   ╚══════════════════════════════════════════════════════════╝
 
   Использование: opencode-db <команда> [флаги]

cmd_costs.py

@@ -3,13 +3,28 @@
 Стоимость берётся напрямую из поля session.cost БД OpenCode.
 """
 
+import argparse
+
 from db import SessionError, get_session_info, get_session_title, parse_model
 from i18n import _
-from utils import format_cost, format_tokens
+from utils import build_help_epilog, format_cost, format_tokens
+
+_COSTS_EXAMPLES = [
+    ("", "help.costs.e0"),
+    ("<session_id>", "help.costs.e1"),
+    ("--total", "help.costs.e2"),
+    ("--project proj_xxx", "help.costs.e3"),
+    ("--json", "help.costs.e4"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("costs", help=_("help.cmd.costs"))
+    p = subparsers.add_parser(
+        "costs",
+        help=_("help.cmd.costs"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("costs", _COSTS_EXAMPLES),
+    )
     p.add_argument("session_id", nargs="?", help="Session ID")
     p.add_argument("--project", type=str, help="Filter by project")
     p.add_argument("--total", action="store_true", help="Total across all sessions")

cmd_delete.py

@@ -1,5 +1,7 @@
 """Команда delete: удаление сессии."""
 
+import argparse
+
 from db import (
     SessionError,
     get_message_count,
@@ -9,11 +11,22 @@
     parse_model,
 )
 from i18n import _
-from utils import confirm, format_cost, format_ts
+from utils import build_help_epilog, confirm, format_cost, format_ts
+
+_DELETE_EXAMPLES = [
+    ("<session_id>", "help.delete.e0"),
+    ("<session_id> --dry-run", "help.delete.e1"),
+    ("<session_id> --force", "help.delete.e2"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("delete", help=_("help.cmd.delete"))
+    p = subparsers.add_parser(
+        "delete",
+        help=_("help.cmd.delete"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("delete", _DELETE_EXAMPLES),
+    )
     p.add_argument("session_id", help="Session ID to delete")
     p.add_argument("--dry-run", action="store_true", help="Preview without deleting")
     p.add_argument("--force", "-f", action="store_true", help="Skip confirmation")

cmd_export.py

@@ -6,6 +6,7 @@
   - export (без аргументов)      — интерактивный выбор из списка
 """
 
+import argparse
 import os
 
 from db import (
@@ -19,11 +20,25 @@
 )
 from formatters import collect_snapshot, format_part_to_md, update_log
 from i18n import _
-from utils import format_cost, format_ts, format_ts_short
+from utils import build_help_epilog, format_cost, format_ts, format_ts_short
+
+_EXPORT_EXAMPLES = [
+    ("<session_id>", "help.export.e0"),
+    ("--latest", "help.export.e1"),
+    ("", "help.export.e2"),
+    ("--full", "help.export.e3"),
+    ("--force", "help.export.e4"),
+    ('--note "text"', "help.export.e5"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("export", help=_("help.cmd.export"))
+    p = subparsers.add_parser(
+        "export",
+        help=_("help.cmd.export"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("export", _EXPORT_EXAMPLES),
+    )
     p.add_argument(
         "session_id",
         nargs="?",

cmd_help.py

@@ -1,17 +1,37 @@
 """Команда help: подробная справка по opencode-db."""
 
+import argparse
 from typing import Literal
 
 from i18n import _
+from utils import build_help_epilog
+
+_HELP_EXAMPLES = [
+    ("", "help.help.e0"),
+    ("<command>", "help.help.e1"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("help", help=_("help.cmd.help"))
+    p = subparsers.add_parser(
+        "help",
+        help=_("help.cmd.help"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("help", _HELP_EXAMPLES),
+    )
     p.add_argument("topic", nargs="?", help="Command name")
     p.add_argument("--json", action="store_true", help="JSON output")
 
 
 _COMMANDS = [
+    (
+        "help",
+        "help.cmd.help",
+        [
+            ("", "help.help.e0"),
+            ("<command>", "help.help.e1"),
+        ],
+    ),
     (
         "list",
         "help.cmd.list",
@@ -173,8 +193,14 @@ def _print_command_help(cmd_name) -> Literal[1] | Literal[0]:
 
     desc_key, examples = entry
     print()
-    print(_("help.cmd_header", cmd=cmd_name, desc=_(desc_key)))
+    print(f"  {'─' * 55}")
+    print(f"  {_('help.cmd_header', cmd=cmd_name, desc=_(desc_key))}")
+    print(f"  {'─' * 55}")
+    print()
+    print(f"  {_('help.flags_header', cmd=cmd_name)}")
+    print(f"    opencode-db {cmd_name} --help")
     print()
+    print(f"  {_('help.usage_header', cmd=cmd_name)}")
     for flag, example_key in examples:
         example_desc = _(example_key)
         if flag:

cmd_info.py

@@ -1,5 +1,7 @@
 """Команда info: детальная информация о сессии."""
 
+import argparse
+
 from db import (
     SessionError,
     get_children_sessions,
@@ -13,11 +15,21 @@
     parse_model,
 )
 from i18n import _
-from utils import format_cost, format_tokens, format_ts
+from utils import build_help_epilog, format_cost, format_tokens, format_ts
+
+_INFO_EXAMPLES = [
+    ("<session_id>", "help.info.e0"),
+    ("<session_id> --json", "help.info.e1"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("info", help=_("help.cmd.info"))
+    p = subparsers.add_parser(
+        "info",
+        help=_("help.cmd.info"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("info", _INFO_EXAMPLES),
+    )
     p.add_argument("session_id", help="Session ID")
     p.add_argument("--json", action="store_true", help="JSON output")
 

cmd_list.py

@@ -1,16 +1,30 @@
 """Команда list: список сессий с фильтрацией и сортировкой."""
 
+import argparse
 from typing import Literal
 
 import db as db_module
 from db import get_session_title, parse_model
 from formatters import print_json, print_table_simple
 from i18n import _
-from utils import format_ts
+from utils import build_help_epilog, format_ts
+
+_LIST_EXAMPLES = [
+    ("", "help.list.e0"),
+    ("--limit 10", "help.list.e1"),
+    ("--sort cost", "help.list.e2"),
+    ("--project proj_xxx", "help.list.e3"),
+    ("--json", "help.list.e4"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("list", help=_("help.cmd.list"))
+    p = subparsers.add_parser(
+        "list",
+        help=_("help.cmd.list"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("list", _LIST_EXAMPLES),
+    )
     p.add_argument("--limit", type=int, default=25, help="Max results (default 25)")
     p.add_argument("--offset", type=int, default=0, help="Offset")
     p.add_argument("--project", type=str, help="Filter by project ID")

cmd_projects.py

@@ -1,13 +1,24 @@
 """Команда projects: список проектов со статистикой."""
 
+import argparse
 from typing import Literal
 
 from i18n import _
-from utils import format_cost, format_tokens, format_ts
+from utils import build_help_epilog, format_cost, format_tokens, format_ts
+
+_PROJECTS_EXAMPLES = [
+    ("", "help.projects.e0"),
+    ("--json", "help.projects.e1"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("projects", help=_("help.cmd.projects"))
+    p = subparsers.add_parser(
+        "projects",
+        help=_("help.cmd.projects"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("projects", _PROJECTS_EXAMPLES),
+    )
     p.add_argument("--json", action="store_true", help="JSON output")
 
 

cmd_prune.py

@@ -1,15 +1,26 @@
 """Команда prune: массовая очистка старых сессий."""
 
-# from db import get_session_info, get_session_title, parse_model, \
-#     get_message_count, get_part_count
+import argparse
 from typing import Literal
 
 from i18n import _
-from utils import confirm, format_ts, parse_time_spec
+from utils import build_help_epilog, confirm, format_ts, parse_time_spec
+
+_PRUNE_EXAMPLES = [
+    ("--older-than 90d", "help.prune.e0"),
+    ("--keep-last 20", "help.prune.e1"),
+    ("--dry-run", "help.prune.e2"),
+    ("--force", "help.prune.e3"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("prune", help=_("help.cmd.prune"))
+    p = subparsers.add_parser(
+        "prune",
+        help=_("help.cmd.prune"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("prune", _PRUNE_EXAMPLES),
+    )
     p.add_argument("--older-than", type=str, help="Delete sessions older than (30d, 6m, 1y)")
     p.add_argument("--keep-last", type=int, help="Keep N most recent sessions")
     p.add_argument("--project", type=str, help="Limit to project")

cmd_search.py

@@ -1,14 +1,26 @@
 """Команда search: поиск по тексту сообщений и частей."""
 
+import argparse
 import json
 
 from db import SessionError, resolve_session_id
 from i18n import _
-from utils import format_ts
+from utils import build_help_epilog, format_ts
+
+_SEARCH_EXAMPLES = [
+    ('"text"', "help.search.e0"),
+    ('"text" --session ses_xxx', "help.search.e1"),
+    ('"text" --json', "help.search.e2"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("search", help=_("help.cmd.search"))
+    p = subparsers.add_parser(
+        "search",
+        help=_("help.cmd.search"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("search", _SEARCH_EXAMPLES),
+    )
     p.add_argument("query", help="Search text")
     p.add_argument("--session", type=str, help="Limit to session")
     p.add_argument("--limit", type=int, default=30, help="Max results")

cmd_stats.py

@@ -1,14 +1,25 @@
 """Команда stats: общая статистика по базе данных."""
 
+import argparse
 from typing import Literal
 
 from db import parse_model
 from i18n import _
-from utils import format_cost, format_tokens, format_ts
+from utils import build_help_epilog, format_cost, format_tokens, format_ts
+
+_STATS_EXAMPLES = [
+    ("", "help.stats.e0"),
+    ("--json", "help.stats.e1"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("stats", help=_("help.cmd.stats"))
+    p = subparsers.add_parser(
+        "stats",
+        help=_("help.cmd.stats"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("stats", _STATS_EXAMPLES),
+    )
     p.add_argument("--json", action="store_true", help="JSON output")
 
 

cmd_todos.py

@@ -1,12 +1,26 @@
 """Команда todos: просмотр задач (todo) из сессий."""
 
+import argparse
+
 from db import SessionError, resolve_session_id
 from i18n import _
-from utils import format_ts
+from utils import build_help_epilog, format_ts
+
+_TODOS_EXAMPLES = [
+    ("", "help.todos.e0"),
+    ("<session_id>", "help.todos.e1"),
+    ("--status pending", "help.todos.e2"),
+    ("--json", "help.todos.e3"),
+]
 
 
 def register(subparsers) -> None:
-    p = subparsers.add_parser("todos", help=_("help.cmd.todos"))
+    p = subparsers.add_parser(
+        "todos",
+        help=_("help.cmd.todos"),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=build_help_epilog("todos", _TODOS_EXAMPLES),
+    )
     p.add_argument("session_id", nargs="?", help="Session ID")
     p.add_argument(
         "--status",