opencode-db 0.7.0__tar.gz → 0.7.3__tar.gz

{opencode_db-0.7.0/opencode_db.egg-info → opencode_db-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-db
-Version: 0.7.0
+Version: 0.7.3
 Summary: OpenCode database CLI manager — browse, export, analyze, clean up sessions
 Project-URL: Homepage, https://github.com/VasilevNStas/opencode-db
 Project-URL: Source, https://github.com/VasilevNStas/opencode-db
@@ -17,12 +17,15 @@ Dynamic: license-file
 # opencode-db
 
 [![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/VasilevNStas/opencode-db/blob/master/LICENSE)
 
 **CLI for OpenCode's local database.** OpenCode saves every agent session, conversation, token usage, and cost in a local SQLite file. This tool lets you inspect, export, analyze, and clean up that data.
 
 ```bash
 pip install opencode-db
+
+# recommended if your system python3 is older than 3.12:
+uv tool install opencode-db
 ```
 
 ## Quick start
@@ -54,6 +57,6 @@ pip install opencode-db         # zero external dependencies
 
 ## Requirements
 
-- Python 3.12+
+- Python 3.12+ — the CLI checks the interpreter at startup and exits with a clear message instead of an `ImportError` on older versions
 - [OpenCode](https://opencode.ai) (must have been run at least once)
 - macOS / Linux

{opencode_db-0.7.0 → opencode_db-0.7.3}/README.md

@@ -8,6 +8,8 @@
 
 **OpenCode stores everything in a local SQLite database.** Every agent session, conversation, token usage, and cost is saved automatically. `opencode-db` is the CLI tool to work with that database — list sessions, export conversations to Markdown, track token costs, prune old data, and more.
 
+[Русская версия](docs/README.ru.md)
+
 ```
 opencode-db help        # full reference with examples
 opencode-db list        # list recent sessions
@@ -22,9 +24,10 @@ opencode-db costs --total  # total token costs
 
 ### Requirements
 
-- Python 3.12+
+- Python 3.12+ — `opencode-db` refuses to start on older interpreters with a clear message (no cryptic `ImportError`)
 - OpenCode (must have been run at least once — the database is created automatically)
 - macOS / Linux
+- [`uv`](https://docs.astral.sh/uv/) — optional, but recommended for installing and running on systems whose default `python3` is older than 3.12
 
 ### Database location
 
@@ -51,13 +54,26 @@ opencode-db --db-path /path/to/opencode.db stats
 
 The `--db-path` flag takes precedence over the environment variable.
 
-### One-command install (recommended)
+### Recommended: uv
+
+If your system `python3` is older than 3.12 (for example, macOS ships 3.9), use `uv` — it installs the tool into an isolated environment with a supported interpreter:
+
+```bash
+uv tool install opencode-db
+# with enhanced Markdown rendering:
+uv tool install "opencode-db[rich]"
+
+# one-off run without installing:
+uvx opencode-db stats
+```
+
+### One-command install
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/VasilevNStas/opencode-db/master/install.sh | sh
 ```
 
-Downloads everything to `~/.local/share/opencode-db/` and creates `~/.local/bin/opencode-db`.
+Downloads everything to `~/.local/share/opencode-db/` and creates `~/.local/bin/opencode-db`. The installer looks for Python 3.12+ (including interpreters managed by `uv` or `pyenv`) and writes the discovered path into the launcher shebang.
 
 ### pip / pipx install
 
@@ -67,7 +83,7 @@ pipx install opencode-db
 pip install opencode-db
 ```
 
-[Zero external dependencies](https://treyhunner.com/2015/12/python-imports-and-path-manipulation/) — pure Python standard library only.
+[Zero external dependencies](https://treyhunner.com/2015/12/python-imports-and-path-manipulation/) — pure Python standard library only (`rich` is optional).
 
 ### Manual install
 
@@ -82,12 +98,22 @@ git clone https://github.com/VasilevNStas/opencode-db.git ~/.local/share/opencod
 ```bash
 cat > ~/.local/bin/opencode-db << 'SCRIPT'
 #!/usr/bin/env python3
-import sys, os
+import os
+import sys
+
+if sys.version_info < (3, 12):
+    print(
+        "opencode-db requires Python 3.12+; current: %s (%s)"
+        % (".".join(map(str, sys.version_info[:3])), sys.executable),
+        file=sys.stderr,
+    )
+    raise SystemExit(1)
+
 PKG_DIR = os.path.expanduser("~/.local/share/opencode-db")
 if PKG_DIR not in sys.path:
     sys.path.insert(0, PKG_DIR)
-import cli
-sys.exit(cli.main())
+from opencode_db.cli import main
+sys.exit(main())
 SCRIPT
 chmod +x ~/.local/bin/opencode-db
 ```
@@ -483,49 +509,56 @@ Example output:
 ## Project architecture
 
 ```
-~/.local/bin/opencode-db                  ← entry point (in $PATH)
+opencode-db/
+├── opencode_db/                          ← Python package (installed as opencode_db)
+│   ├── __init__.py                       ← package init + Python version guard
+│   ├── __main__.py                       ← python3 -m opencode_db
+│   ├── cli.py                            ← argparse + command dispatcher
+│   ├── config.py                         ← constants and paths
+│   ├── db.py                             ← SQLite queries
+│   ├── formatters.py                     ← tables, JSON, Markdown, snapshots
+│   ├── i18n.py                           ← localization (EN/RU, 280 keys)
+│   ├── markdown_to_ansi.py               ← Markdown → ANSI renderer for `view`
+│   ├── runtime.py                        ← Python 3.12+ version guard
+│   ├── utils.py                          ← date/token formatting, validation
+│   └── commands/
+│       ├── __init__.py                   ← command registry
+│       ├── cmd_list.py                   ← opencode-db list
+│       ├── cmd_info.py                   ← opencode-db info
+│       ├── cmd_export.py                 ← opencode-db export
+│       ├── cmd_delete.py                 ← opencode-db delete
+│       ├── cmd_costs.py                  ← opencode-db costs
+│       ├── cmd_prune.py                  ← opencode-db prune
+│       ├── cmd_search.py                 ← opencode-db search
+│       ├── cmd_tree.py                   ← opencode-db tree
+│       ├── cmd_projects.py               ← opencode-db projects
+│       ├── cmd_stats.py                  ← opencode-db stats
+│       ├── cmd_todos.py                  ← opencode-db todos
+│       ├── cmd_vacuum.py                 ← opencode-db vacuum
+│       ├── cmd_view.py                   ← opencode-db view
+│       └── cmd_help.py                   ← opencode-db help
 │
-~/.local/share/opencode-db/               ← all source code
-│
-├── __init__.py                           ← executable entry point
-├── __main__.py                           ← python -m opencode_db
-├── cli.py                                ← argparse + command dispatcher
-│
-├── config.py                             ← constants and paths
-├── db.py                                 ← SQLite queries
-├── utils.py                              ← date/token formatting, validation
-├── formatters.py                         ← tables, JSON, Markdown, snapshots
-├── i18n.py                               ← localization (EN/RU, 238 keys)
-│
-├── commands/
-│   └── __init__.py                       ← command registry
-│
-├── cmd_list.py                           ← opencode-db list
-├── cmd_info.py                           ← opencode-db info
-├── cmd_export.py                         ← opencode-db export
-├── cmd_delete.py                         ← opencode-db delete
-├── cmd_costs.py                          ← opencode-db costs
-├── cmd_prune.py                          ← opencode-db prune
-├── cmd_search.py                         ← opencode-db search
-├── cmd_tree.py                           ← opencode-db tree
-├── cmd_projects.py                       ← opencode-db projects
-├── cmd_stats.py                          ← opencode-db stats
-├── cmd_todos.py                          ← opencode-db todos
-├── cmd_vacuum.py                         ← opencode-db vacuum
-└── cmd_help.py                           ← opencode-db help
-
-README.md                                 ← this file (English)
-README.ru.md                              ← documentation in Russian
-opencode-db-commands.json                 ← OpenCode TUI custom commands config
+├── docs/
+│   ├── README.ru.md                      ← documentation in Russian
+│   └── README_PYPI.md                    ← PyPI page
+├── contrib/
+│   └── opencode-db-commands.json         ← OpenCode TUI custom commands config
+├── tests/
+├── README.md                             ← this file (English)
+├── LICENSE
+├── Makefile
+├── pyproject.toml
+└── install.sh
 ```
 
 ### How it works
 
-1. The launcher script at `~/.local/bin/opencode-db` (a shebang Python script) adds `~/.local/share/opencode-db/` to `sys.path` and calls `cli.main()`.
-2. `cli.py` builds an `argparse` parser with subparsers from every command module and dispatches the call.
-3. Each command is a separate `cmd_*.py` module exporting two functions: `register(subparsers)` and `run(args, db)`.
-4. `db.py` opens a connection to OpenCode's SQLite database (`~/.local/share/opencode/opencode.db`).
-5. Destructive operations (`delete`, `prune`) always require confirmation (or `--force`).
+1. The console script `opencode-db` (or `python3 -m opencode_db`) imports `opencode_db.cli` and calls `main()`.
+2. `runtime.require_python()` checks the interpreter before importing `cli`/`db`; on Python < 3.12 it prints a clear message with remediation steps instead of failing with `ImportError`.
+3. `cli.py` builds an `argparse` parser with subparsers from every command module and dispatches the call.
+4. Each command is a separate `opencode_db/commands/cmd_*.py` module exporting two functions: `register(subparsers)` and `run(args, db)`.
+5. `db.py` opens a connection to OpenCode's SQLite database (`~/.local/share/opencode/opencode.db`).
+6. Destructive operations (`delete`, `prune`) always require confirmation (or `--force`).
 
 ### Database schema (key tables)
 
@@ -558,7 +591,7 @@ This runs the command directly and shows the output — **no tokens are consumed
 
 ### Custom `/db` command (uses AI, consumes tokens)
 
-Add the commands from `opencode-db-commands.json` to your project's `opencode.json`:
+Add the commands from `contrib/opencode-db-commands.json` to your project's `opencode.json`:
 
 ```json
 {
@@ -586,7 +619,7 @@ Then in the TUI:
 
 A ready-to-use config file is provided at:
 ```
-~/.local/share/opencode-db/opencode-db-commands.json
+~/.local/share/opencode-db/contrib/opencode-db-commands.json
 ```
 
 ---
@@ -617,7 +650,7 @@ opencode-db --lang en help        # English help text
 opencode-db --lang en stats       # English statistics
 ```
 
-The `--lang` flag applies to any command. All 238 UI strings are translated. Data content (session titles, project names, etc.) remains in its original language.
+The `--lang` flag applies to any command. All 280 UI strings are translated. Data content (session titles, project names, etc.) remains in its original language.
 
 The language can also be set via environment variable `OPENCODE_DB_LANG=en`.
 
@@ -659,13 +692,57 @@ Use a longer prefix or the full session ID (use `list --json` to find it).
 
 If the database is being used by another process (e.g., OpenCode is running), VACUUM may fail. Close OpenCode and try again.
 
+### `ImportError: cannot import name 'UTC' from 'datetime'`
+
+This means `opencode-db` is running on Python older than 3.12 (for example, the system Python 3.9). Check:
+
+```bash
+python3 --version
+```
+
+Fix with `uv` (recommended):
+
+```bash
+uv python install 3.13
+uv tool install opencode-db
+opencode-db stats
+```
+
+Or run the repository checkout with an explicit interpreter:
+
+```bash
+uvx --from . opencode-db stats
+# alternative for a persistent dev environment:
+uv run --python 3.13 opencode-db stats
+```
+
+After changing the interpreter, rerun `install.sh` to regenerate the `~/.local/bin/opencode-db` launcher.
+
 ---
 
 ## Development
 
+### Local development
+
+Requires Python 3.12+ and `pytest`/`ruff`:
+
+```bash
+git clone https://github.com/VasilevNStas/opencode-db.git
+cd opencode-db
+
+uv venv --python 3.13
+source .venv/bin/activate
+uv pip install -e ".[rich]"
+uv pip install pytest ruff==0.17.1
+
+make check          # check-python + ruff + 191 tests
+```
+
+`make check` fails fast with a clear message if the active interpreter is older than 3.12.
+
 ### Adding a new command
 
-1. Create `cmd_xxx.py`:
+1. Create `opencode_db/commands/cmd_xxx.py`:
 
 ```python
 def register(subparsers):
@@ -677,7 +754,7 @@ def run(args, db):
     return 0
 ```
 
-2. Register it in `commands/__init__.py`:
+2. Register it in `opencode_db/commands/__init__.py`:
 
 ```python
 import cmd_xxx
@@ -692,10 +769,11 @@ The command will appear in `--help` automatically.
 python3 ~/.local/share/opencode-db list
 ```
 
-Or as a module:
+Or from the repository root (Python 3.12+):
 
 ```bash
 python3 -m opencode_db list
+uvx --from . opencode-db list
 ```
 
 ---

{opencode_db-0.7.0 → opencode_db-0.7.3/docs}/README_PYPI.md

@@ -1,12 +1,15 @@
 # opencode-db
 
 [![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/VasilevNStas/opencode-db/blob/master/LICENSE)
 
 **CLI for OpenCode's local database.** OpenCode saves every agent session, conversation, token usage, and cost in a local SQLite file. This tool lets you inspect, export, analyze, and clean up that data.
 
 ```bash
 pip install opencode-db
+
+# recommended if your system python3 is older than 3.12:
+uv tool install opencode-db
 ```
 
 ## Quick start
@@ -38,6 +41,6 @@ pip install opencode-db         # zero external dependencies
 
 ## Requirements
 
-- Python 3.12+
+- Python 3.12+ — the CLI checks the interpreter at startup and exits with a clear message instead of an `ImportError` on older versions
 - [OpenCode](https://opencode.ai) (must have been run at least once)
 - macOS / Linux

opencode_db-0.7.3/opencode_db/__init__.py

@@ -0,0 +1,5 @@
+"""opencode-db: CLI for OpenCode's local SQLite database."""
+
+from .runtime import require_python
+
+require_python()

opencode_db-0.7.3/opencode_db/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python3 -m opencode_db`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db}/cli.py

@@ -7,14 +7,20 @@
   - Единообразный интерфейс
 """
 
+from __future__ import annotations
+
 import argparse
 import os
 import sys
 from typing import Any, Literal
 
-import commands
-from db import get_db
-from i18n import _, set_lang
+from .runtime import require_python
+
+require_python()
+
+from . import commands  # noqa: E402
+from .db import get_db  # noqa: E402
+from .i18n import _, set_lang  # noqa: E402
 
 
 def build_parser() -> argparse.ArgumentParser:

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db}/commands/__init__.py

@@ -5,25 +5,27 @@
   - run(args, db) — выполняет команду
 
 Добавление новой команды:
-  1. Создать cmd_xxx.py
-  2. Добавить import cmd_xxx
+  1. Создать opencode_db/commands/cmd_xxx.py
+  2. Добавить `from . import cmd_xxx`
   3. Добавить "xxx": cmd_xxx в COMMANDS
 """
 
-import cmd_costs
-import cmd_delete
-import cmd_export
-import cmd_help
-import cmd_info
-import cmd_list
-import cmd_projects
-import cmd_prune
-import cmd_search
-import cmd_stats
-import cmd_todos
-import cmd_tree
-import cmd_vacuum
-import cmd_view
+from . import (
+    cmd_costs,
+    cmd_delete,
+    cmd_export,
+    cmd_help,
+    cmd_info,
+    cmd_list,
+    cmd_projects,
+    cmd_prune,
+    cmd_search,
+    cmd_stats,
+    cmd_todos,
+    cmd_tree,
+    cmd_vacuum,
+    cmd_view,
+)
 
 # Словарь {имя_команды: модуль}
 # Модуль должен иметь register(subparsers) и run(args, db)

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db/commands}/cmd_costs.py

@@ -5,9 +5,9 @@
 
 import argparse
 
-from db import SessionError, get_session_info, get_session_title, parse_model
-from i18n import _
-from utils import build_help_epilog, format_cost, format_tokens
+from ..db import SessionError, get_session_info, get_session_title, parse_model
+from ..i18n import _
+from ..utils import build_help_epilog, format_cost, format_tokens
 
 _COSTS_EXAMPLES = [
     ("", "help.costs.e0"),
@@ -57,7 +57,7 @@ def _show_session(db, session_id, as_json) -> int:
     cost = info["cost"] or 0
 
     if as_json:
-        from formatters import print_json
+        from ..formatters import print_json
 
         print_json(
             {
@@ -115,7 +115,7 @@ def _show_total(db, project_id, as_json) -> int:
     total_tr = row["tr"] or 0
 
     if as_json:
-        from formatters import print_json
+        from ..formatters import print_json
 
         print_json(
             {
@@ -165,7 +165,7 @@ def _show_list(db, project_id, limit, as_json) -> int:
     ).fetchall()
 
     if as_json:
-        from formatters import print_json
+        from ..formatters import print_json
 
         data = []
         for r in rows:
@@ -183,7 +183,7 @@ def _show_list(db, project_id, limit, as_json) -> int:
         print_json(data)
         return 0
 
-    from formatters import print_table_simple
+    from ..formatters import print_table_simple
 
     table = []
     for r in rows:

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db/commands}/cmd_delete.py

@@ -2,7 +2,7 @@
 
 import argparse
 
-from db import (
+from ..db import (
     SessionError,
     get_message_count,
     get_part_count,
@@ -11,8 +11,8 @@ from db import (
     get_session_title,
     parse_model,
 )
-from i18n import _
-from utils import build_help_epilog, confirm, format_cost, format_ts, parse_date, parse_time_spec
+from ..i18n import _
+from ..utils import build_help_epilog, confirm, format_cost, format_ts, parse_date, parse_time_spec
 
 _DELETE_EXAMPLES = [
     ("<session_id>", "help.delete.e0"),

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db/commands}/cmd_export.py

@@ -9,7 +9,7 @@
 import argparse
 import os
 
-from db import (
+from ..db import (
     SessionError,
     get_latest_session,
     get_messages,
@@ -18,9 +18,9 @@ from db import (
     get_session_title,
     parse_model,
 )
-from formatters import collect_snapshot, format_part_to_md, update_log
-from i18n import _
-from utils import build_help_epilog, format_cost, format_ts, format_ts_short
+from ..formatters import collect_snapshot, format_part_to_md, update_log
+from ..i18n import _
+from ..utils import build_help_epilog, format_cost, format_ts, format_ts_short
 
 _EXPORT_EXAMPLES = [
     ("<session_id>", "help.export.e0"),

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db/commands}/cmd_help.py

@@ -3,8 +3,8 @@
 import argparse
 from typing import Literal
 
-from i18n import _
-from utils import build_help_epilog
+from ..i18n import _
+from ..utils import build_help_epilog
 
 _HELP_EXAMPLES = [
     ("", "help.help.e0"),

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db/commands}/cmd_info.py

@@ -2,7 +2,7 @@
 
 import argparse
 
-from db import (
+from ..db import (
     SessionError,
     get_children_sessions,
     get_message_count,
@@ -14,8 +14,8 @@ from db import (
     get_session_todos,
     parse_model,
 )
-from i18n import _
-from utils import build_help_epilog, format_cost, format_tokens, format_ts
+from ..i18n import _
+from ..utils import build_help_epilog, format_cost, format_tokens, format_ts
 
 _INFO_EXAMPLES = [
     ("<session_id>", "help.info.e0"),
@@ -104,7 +104,7 @@ def run(args, db) -> int:
         if parent:
             data["parent"] = {"id": parent["id"], "title": parent["title"]}
 
-        from formatters import print_json
+        from ..formatters import print_json
 
         print_json(data)
         return 0

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db/commands}/cmd_list.py

@@ -3,11 +3,11 @@
 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 build_help_epilog, format_ts
+from .. 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 build_help_epilog, format_ts
 
 _LIST_EXAMPLES = [
     ("", "help.list.e0"),

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db/commands}/cmd_projects.py

@@ -3,8 +3,8 @@
 import argparse
 from typing import Literal
 
-from i18n import _
-from utils import build_help_epilog, format_cost, format_tokens, format_ts
+from ..i18n import _
+from ..utils import build_help_epilog, format_cost, format_tokens, format_ts
 
 _PROJECTS_EXAMPLES = [
     ("", "help.projects.e0"),
@@ -37,7 +37,7 @@ def run(args, db) -> Literal[0]:
     """).fetchall()
 
     if args.json:
-        from formatters import print_json
+        from ..formatters import print_json
 
         data = []
         for r in rows:
@@ -59,7 +59,7 @@ def run(args, db) -> Literal[0]:
         print_json(data)
         return 0
 
-    from formatters import print_table_simple
+    from ..formatters import print_table_simple
 
     table = []
     for r in rows:

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db/commands}/cmd_prune.py

@@ -2,9 +2,9 @@
 
 import argparse
 
-from cmd_delete import run as delete_run
-from i18n import _
-from utils import build_help_epilog
+from ..i18n import _
+from ..utils import build_help_epilog
+from .cmd_delete import run as delete_run
 
 _PRUNE_EXAMPLES = [
     ("--older-than 90d", "help.prune.e0"),

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db/commands}/cmd_search.py

@@ -3,9 +3,9 @@
 import argparse
 import json
 
-from db import SessionError, resolve_session_id
-from i18n import _
-from utils import build_help_epilog, format_ts
+from ..db import SessionError, resolve_session_id
+from ..i18n import _
+from ..utils import build_help_epilog, format_ts
 
 _SEARCH_EXAMPLES = [
     ('"text"', "help.search.e0"),
@@ -103,7 +103,7 @@ def run(args, db) -> int:
             break
 
     if args.json:
-        from formatters import print_json
+        from ..formatters import print_json
 
         print_json(results)
         return 0

{opencode_db-0.7.0 → opencode_db-0.7.3/opencode_db/commands}/cmd_stats.py

@@ -3,9 +3,9 @@
 import argparse
 from typing import Literal
 
-from db import parse_model
-from i18n import _
-from utils import build_help_epilog, format_cost, format_tokens, format_ts
+from ..db import parse_model
+from ..i18n import _
+from ..utils import build_help_epilog, format_cost, format_tokens, format_ts
 
 _STATS_EXAMPLES = [
     ("", "help.stats.e0"),
@@ -64,7 +64,7 @@ def run(args, db) -> Literal[0]:
     """).fetchall()
 
     if args.json:
-        from formatters import print_json
+        from ..formatters import print_json
 
         data = {
             "sessions": session_count,