rb-bukvarix 0.6.6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. rb_bukvarix-0.6.6/.gitignore +32 -0
  2. rb_bukvarix-0.6.6/LICENSE +21 -0
  3. rb_bukvarix-0.6.6/PKG-INFO +132 -0
  4. rb_bukvarix-0.6.6/README.md +111 -0
  5. rb_bukvarix-0.6.6/pyproject.toml +184 -0
  6. rb_bukvarix-0.6.6/src/bukvarix/__init__.py +1 -0
  7. rb_bukvarix-0.6.6/src/bukvarix/_distribution.py +24 -0
  8. rb_bukvarix-0.6.6/src/bukvarix/cli.py +75 -0
  9. rb_bukvarix-0.6.6/src/bukvarix/commands/__init__.py +1 -0
  10. rb_bukvarix-0.6.6/src/bukvarix/commands/auth.py +66 -0
  11. rb_bukvarix-0.6.6/src/bukvarix/commands/config.py +87 -0
  12. rb_bukvarix-0.6.6/src/bukvarix/commands/db.py +256 -0
  13. rb_bukvarix-0.6.6/src/bukvarix/commands/describe.py +34 -0
  14. rb_bukvarix-0.6.6/src/bukvarix/commands/doctor.py +70 -0
  15. rb_bukvarix-0.6.6/src/bukvarix/commands/freq.py +117 -0
  16. rb_bukvarix-0.6.6/src/bukvarix/commands/init.py +53 -0
  17. rb_bukvarix-0.6.6/src/bukvarix/commands/project.py +55 -0
  18. rb_bukvarix-0.6.6/src/bukvarix/commands/search.py +148 -0
  19. rb_bukvarix-0.6.6/src/bukvarix/commands/site.py +108 -0
  20. rb_bukvarix-0.6.6/src/bukvarix/commands/skill.py +138 -0
  21. rb_bukvarix-0.6.6/src/bukvarix/commands/stats.py +23 -0
  22. rb_bukvarix-0.6.6/src/bukvarix/commands/status.py +35 -0
  23. rb_bukvarix-0.6.6/src/bukvarix/core/__init__.py +1 -0
  24. rb_bukvarix-0.6.6/src/bukvarix/core/api.py +242 -0
  25. rb_bukvarix-0.6.6/src/bukvarix/core/data_files.py +20 -0
  26. rb_bukvarix-0.6.6/src/bukvarix/core/db.py +746 -0
  27. rb_bukvarix-0.6.6/src/bukvarix/core/deps.py +165 -0
  28. rb_bukvarix-0.6.6/src/bukvarix/core/errors.py +285 -0
  29. rb_bukvarix-0.6.6/src/bukvarix/core/models.py +25 -0
  30. rb_bukvarix-0.6.6/src/bukvarix/core/normalize.py +207 -0
  31. rb_bukvarix-0.6.6/src/bukvarix/core/opencli.py +285 -0
  32. rb_bukvarix-0.6.6/src/bukvarix/core/query_syntax.py +37 -0
  33. rb_bukvarix-0.6.6/src/bukvarix/core/services.py +147 -0
  34. rb_bukvarix-0.6.6/src/bukvarix/core/skills.py +64 -0
  35. rb_bukvarix-0.6.6/src/bukvarix/core/version.py +89 -0
  36. rb_bukvarix-0.6.6/src/bukvarix/data/SKILL.md +109 -0
  37. rb_bukvarix-0.6.6/src/bukvarix/data/__init__.py +1 -0
  38. rb_bukvarix-0.6.6/src/bukvarix/output/__init__.py +281 -0
  39. rb_bukvarix-0.6.6/src/bukvarix/output/human.py +97 -0
  40. rb_bukvarix-0.6.6/src/bukvarix/output/json.py +11 -0
  41. rb_bukvarix-0.6.6/tests/__init__.py +1 -0
  42. rb_bukvarix-0.6.6/tests/conftest.py +102 -0
  43. rb_bukvarix-0.6.6/tests/contracts/data/phrases.txt +5 -0
  44. rb_bukvarix-0.6.6/tests/contracts/fixtures.yaml +19 -0
  45. rb_bukvarix-0.6.6/tests/contracts/schema.json +89 -0
  46. rb_bukvarix-0.6.6/tests/contracts/tools-catalog/bukvarix.yaml +20 -0
  47. rb_bukvarix-0.6.6/tests/contracts/windmill/bukvarix.yaml +48 -0
  48. rb_bukvarix-0.6.6/tests/data/contracts/windmill-serp.yaml +106 -0
  49. rb_bukvarix-0.6.6/tests/data/opencli.schema.json +350 -0
  50. rb_bukvarix-0.6.6/tests/help_allowlist.txt +4 -0
  51. rb_bukvarix-0.6.6/tests/snapshots/describe.json +1847 -0
  52. rb_bukvarix-0.6.6/tests/snapshots/help/auth-status.txt +26 -0
  53. rb_bukvarix-0.6.6/tests/snapshots/help/auth.txt +13 -0
  54. rb_bukvarix-0.6.6/tests/snapshots/help/config-get.txt +18 -0
  55. rb_bukvarix-0.6.6/tests/snapshots/help/config-list.txt +13 -0
  56. rb_bukvarix-0.6.6/tests/snapshots/help/config-set.txt +19 -0
  57. rb_bukvarix-0.6.6/tests/snapshots/help/config.txt +14 -0
  58. rb_bukvarix-0.6.6/tests/snapshots/help/db-build-postings.txt +25 -0
  59. rb_bukvarix-0.6.6/tests/snapshots/help/db-import-keywords.txt +27 -0
  60. rb_bukvarix-0.6.6/tests/snapshots/help/db-normalize.txt +19 -0
  61. rb_bukvarix-0.6.6/tests/snapshots/help/db-reindex.txt +20 -0
  62. rb_bukvarix-0.6.6/tests/snapshots/help/db-set-data-date.txt +23 -0
  63. rb_bukvarix-0.6.6/tests/snapshots/help/db-set-path.txt +16 -0
  64. rb_bukvarix-0.6.6/tests/snapshots/help/db.txt +20 -0
  65. rb_bukvarix-0.6.6/tests/snapshots/help/describe.txt +18 -0
  66. rb_bukvarix-0.6.6/tests/snapshots/help/doctor.txt +22 -0
  67. rb_bukvarix-0.6.6/tests/snapshots/help/freq.txt +33 -0
  68. rb_bukvarix-0.6.6/tests/snapshots/help/init.txt +21 -0
  69. rb_bukvarix-0.6.6/tests/snapshots/help/search.txt +45 -0
  70. rb_bukvarix-0.6.6/tests/snapshots/help/site.txt +44 -0
  71. rb_bukvarix-0.6.6/tests/snapshots/help/skill-install.txt +19 -0
  72. rb_bukvarix-0.6.6/tests/snapshots/help/skill-list.txt +13 -0
  73. rb_bukvarix-0.6.6/tests/snapshots/help/skill.txt +13 -0
  74. rb_bukvarix-0.6.6/tests/snapshots/help/stats.txt +14 -0
  75. rb_bukvarix-0.6.6/tests/snapshots/help/status.txt +14 -0
  76. rb_bukvarix-0.6.6/tests/test_api.py +237 -0
  77. rb_bukvarix-0.6.6/tests/test_cli.py +648 -0
  78. rb_bukvarix-0.6.6/tests/test_contract_runner.py +257 -0
  79. rb_bukvarix-0.6.6/tests/test_contracts.py +389 -0
  80. rb_bukvarix-0.6.6/tests/test_db.py +288 -0
  81. rb_bukvarix-0.6.6/tests/test_deps.py +150 -0
  82. rb_bukvarix-0.6.6/tests/test_describe.py +181 -0
  83. rb_bukvarix-0.6.6/tests/test_detach.py +161 -0
  84. rb_bukvarix-0.6.6/tests/test_help.py +495 -0
  85. rb_bukvarix-0.6.6/tests/test_project.py +155 -0
  86. rb_bukvarix-0.6.6/tests/test_scripts.py +54 -0
  87. rb_bukvarix-0.6.6/tests/test_services.py +109 -0
  88. rb_bukvarix-0.6.6/tests/test_skills.py +181 -0
@@ -0,0 +1,32 @@
1
+ # The production database — 44GB+, never belongs in git
2
+ *.duckdb
3
+ *.duckdb.wal
4
+ *.duckdb.backup_*
5
+ *.bak_*
6
+
7
+ # Python
8
+ __pycache__/
9
+ *.pyc
10
+ .venv/
11
+ *.egg-info/
12
+ dist/
13
+ build/
14
+
15
+ # Test/lint/coverage artifacts
16
+ .pytest_cache/
17
+ .ruff_cache/
18
+ .coverage
19
+ htmlcov/
20
+
21
+ # Local project state for a CLI consuming bukvarix (not this repo's own data)
22
+ .bukvarix/state.json
23
+ # mutmut's working copy and results (uv run --group mutation mutmut run)
24
+ mutants/
25
+ # Local env files hold keys: keys never go into the repo (the gate's secret scan)
26
+ .env
27
+ .env.*
28
+ # The root lines Antagor adds
29
+ .DS_Store
30
+ Thumbs.db
31
+ .pdm-build/
32
+ .cache/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Roman Bolandau
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,132 @@
1
+ Metadata-Version: 2.5
2
+ Name: rb-bukvarix
3
+ Version: 0.6.6
4
+ Summary: Keyword frequencies offline: a local Wordstat-alike over Bukvarix dumps.
5
+ Project-URL: Repository, https://github.com/bolandeu/bukvarix
6
+ Author: net.paradox
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Requires-Python: >=3.14
10
+ Requires-Dist: duckdb>=1.1
11
+ Requires-Dist: packaging>=24.0
12
+ Requires-Dist: platformdirs>=4.2
13
+ Requires-Dist: pydantic>=2.6
14
+ Requires-Dist: pymorphy3-dicts-ru>=2.4.417150.4580142
15
+ Requires-Dist: pymorphy3>=2.0.6
16
+ Requires-Dist: rb-credentials<1,>=0.3
17
+ Requires-Dist: rich>=13.7
18
+ Requires-Dist: tomli-w>=1.0
19
+ Requires-Dist: typer<0.29,>=0.27
20
+ Description-Content-Type: text/markdown
21
+
22
+ # Bukvarix
23
+
24
+ Local Wordstat-like CLI over a Bukvarix keyword dump (Moscow, frequencies
25
+ only — no SERP data).
26
+
27
+ ## Development
28
+
29
+ ```bash
30
+ uv sync
31
+ uv run bukvarix --help
32
+ ```
33
+
34
+ The gate before a commit is `gate check`, run from the package root on this
35
+ machine: the command is `[publish] gate_command` in `.agents/antagor/antagor.toml`.
36
+ It covers
37
+ ruff (security `S` rules included), ty, pytest with the coverage floor from
38
+ `pyproject.toml`, the help snapshots and the consumer contracts.
39
+
40
+ ## Release
41
+
42
+ `antagor publish` runs the gate, bumps the last `vX.Y.Z` tag (the version comes
43
+ from the tag — there is no `version =` in `pyproject.toml`), writes
44
+ `CHANGELOG.md`, tags and pushes. At `0.x` a breaking change is a minor bump.
45
+
46
+ ## Install
47
+
48
+ **On this machine, from a local checkout:**
49
+
50
+ ```bash
51
+ uv tool install --editable .
52
+ ```
53
+
54
+ **On any other machine (any OS), from the Gitea package registry:**
55
+
56
+ ```bash
57
+ ```
58
+
59
+ Or from a release tag:
60
+
61
+ ```bash
62
+ uv tool install "rb-bukvarix @ git+https://homeserver.tailee01ab.ts.net:3000/bolandeu/bukvarix.git@vX.Y.Z"
63
+ ```
64
+
65
+ This is also how an AI agent bootstraps this CLI on a fresh machine/sandbox
66
+ where it isn't installed yet — see `src/bukvarix/data/SKILL.md`.
67
+
68
+ Installed under the old distribution name `bukvarix` (before 0.3)? Remove it
69
+ first, otherwise two tools claim the same `bukvarix` command:
70
+ `uv tool uninstall bukvarix`.
71
+
72
+ **Update** an installed copy:
73
+
74
+ ```bash
75
+ uv tool upgrade rb-bukvarix
76
+ ```
77
+
78
+ After install, the command `bukvarix` is available globally on macOS,
79
+ Linux and Windows alike — no shelling out, no hardcoded POSIX paths.
80
+
81
+ To pick up later changes of the `cli-generator` template, run
82
+ `uvx copier update --trust --defaults` in this repo.
83
+
84
+ ## The database
85
+
86
+ `bukvarix` queries a single DuckDB file (~41GB on the real Moscow dump).
87
+ It lives in the user data dir, never in the repo:
88
+ `platformdirs.user_data_dir("bukvarix")/bukvarix.duckdb` — on macOS
89
+ `~/Library/Application Support/bukvarix/bukvarix.duckdb`, on Linux
90
+ `~/.local/share/bukvarix/bukvarix.duckdb`. Path resolution, in order:
91
+
92
+ 1. `BUKVARIX_DB_PATH` env var — explicit override for one process/session.
93
+ 2. `bukvarix db set-path PATH` — persisted via the OS user config dir
94
+ (survives across shells/processes without needing to be sourced from a
95
+ shell profile, which a non-interactive process wouldn't see anyway).
96
+ 3. The user-data default above — the normal case; leave 1 and 2 unset
97
+ unless the database really lives elsewhere.
98
+
99
+ `search`/`freq` fail with a structured `DATABASE_NOT_READY` error if
100
+ nothing has been imported yet; `stats --json` always succeeds and reports
101
+ `keywords_rows: 0` in that case. Building the database from a raw Bukvarix
102
+
103
+ ## Architecture
104
+
105
+ This project follows a fixed CLI architecture:
106
+
107
+ - `src/bukvarix/commands/` — argument parsing only, no business logic.
108
+ - `src/bukvarix/core/` — services (including database-path resolution),
109
+ the DuckDB query/import/normalize layer (`core/db.py`), models, errors.
110
+ - `src/bukvarix/credentials/` — OS keychain (`keyring`) + env vars, kept
111
+ for fleet-wide consistency; unused today (bukvarix has no external API).
112
+ - `src/bukvarix/output/` — human (`rich`) and `--json` rendering.
113
+
114
+ Run `bukvarix doctor` to check environment and database readiness, and
115
+ `bukvarix --help` for the full command surface. Every command supports
116
+ `--json` for machine/agent consumption (envelope: `{"ok": true, ...}` on
117
+ success, `{"ok": false, "error": {"code", "message", "action"}}` on
118
+ failure); human-mode errors go to stderr, so stdout is always safe to
119
+ pipe. `db import-keywords`/`db normalize`/`db reindex` mutate the database
120
+ file in place and require `--confirm` (or an interactive yes) — see
121
+ `AGENTS.md` for the backup discipline around them.
122
+
123
+ `search`/`freq`/`stats`/`db ...` work from any directory against one
124
+ machine-wide database — no `bukvarix init` needed. `init`/`status`/`config`
125
+ exist for parity with this CLI's sibling tools (a project can require a
126
+ minimum CLI version via `.bukvarix/config.toml`'s `[cli] min_version`) but
127
+ hold no data bukvarix's own commands read.
128
+
129
+ See `src/bukvarix/data/SKILL.md` for the agent-facing usage guide bundled
130
+ with this package — install it into an AI tool with `bukvarix skill
131
+ install`, or get it as plain text with `bukvarix --ai` (works even without
132
+ file access).
@@ -0,0 +1,111 @@
1
+ # Bukvarix
2
+
3
+ Local Wordstat-like CLI over a Bukvarix keyword dump (Moscow, frequencies
4
+ only — no SERP data).
5
+
6
+ ## Development
7
+
8
+ ```bash
9
+ uv sync
10
+ uv run bukvarix --help
11
+ ```
12
+
13
+ The gate before a commit is `gate check`, run from the package root on this
14
+ machine: the command is `[publish] gate_command` in `.agents/antagor/antagor.toml`.
15
+ It covers
16
+ ruff (security `S` rules included), ty, pytest with the coverage floor from
17
+ `pyproject.toml`, the help snapshots and the consumer contracts.
18
+
19
+ ## Release
20
+
21
+ `antagor publish` runs the gate, bumps the last `vX.Y.Z` tag (the version comes
22
+ from the tag — there is no `version =` in `pyproject.toml`), writes
23
+ `CHANGELOG.md`, tags and pushes. At `0.x` a breaking change is a minor bump.
24
+
25
+ ## Install
26
+
27
+ **On this machine, from a local checkout:**
28
+
29
+ ```bash
30
+ uv tool install --editable .
31
+ ```
32
+
33
+ **On any other machine (any OS), from the Gitea package registry:**
34
+
35
+ ```bash
36
+ ```
37
+
38
+ Or from a release tag:
39
+
40
+ ```bash
41
+ uv tool install "rb-bukvarix @ git+https://homeserver.tailee01ab.ts.net:3000/bolandeu/bukvarix.git@vX.Y.Z"
42
+ ```
43
+
44
+ This is also how an AI agent bootstraps this CLI on a fresh machine/sandbox
45
+ where it isn't installed yet — see `src/bukvarix/data/SKILL.md`.
46
+
47
+ Installed under the old distribution name `bukvarix` (before 0.3)? Remove it
48
+ first, otherwise two tools claim the same `bukvarix` command:
49
+ `uv tool uninstall bukvarix`.
50
+
51
+ **Update** an installed copy:
52
+
53
+ ```bash
54
+ uv tool upgrade rb-bukvarix
55
+ ```
56
+
57
+ After install, the command `bukvarix` is available globally on macOS,
58
+ Linux and Windows alike — no shelling out, no hardcoded POSIX paths.
59
+
60
+ To pick up later changes of the `cli-generator` template, run
61
+ `uvx copier update --trust --defaults` in this repo.
62
+
63
+ ## The database
64
+
65
+ `bukvarix` queries a single DuckDB file (~41GB on the real Moscow dump).
66
+ It lives in the user data dir, never in the repo:
67
+ `platformdirs.user_data_dir("bukvarix")/bukvarix.duckdb` — on macOS
68
+ `~/Library/Application Support/bukvarix/bukvarix.duckdb`, on Linux
69
+ `~/.local/share/bukvarix/bukvarix.duckdb`. Path resolution, in order:
70
+
71
+ 1. `BUKVARIX_DB_PATH` env var — explicit override for one process/session.
72
+ 2. `bukvarix db set-path PATH` — persisted via the OS user config dir
73
+ (survives across shells/processes without needing to be sourced from a
74
+ shell profile, which a non-interactive process wouldn't see anyway).
75
+ 3. The user-data default above — the normal case; leave 1 and 2 unset
76
+ unless the database really lives elsewhere.
77
+
78
+ `search`/`freq` fail with a structured `DATABASE_NOT_READY` error if
79
+ nothing has been imported yet; `stats --json` always succeeds and reports
80
+ `keywords_rows: 0` in that case. Building the database from a raw Bukvarix
81
+
82
+ ## Architecture
83
+
84
+ This project follows a fixed CLI architecture:
85
+
86
+ - `src/bukvarix/commands/` — argument parsing only, no business logic.
87
+ - `src/bukvarix/core/` — services (including database-path resolution),
88
+ the DuckDB query/import/normalize layer (`core/db.py`), models, errors.
89
+ - `src/bukvarix/credentials/` — OS keychain (`keyring`) + env vars, kept
90
+ for fleet-wide consistency; unused today (bukvarix has no external API).
91
+ - `src/bukvarix/output/` — human (`rich`) and `--json` rendering.
92
+
93
+ Run `bukvarix doctor` to check environment and database readiness, and
94
+ `bukvarix --help` for the full command surface. Every command supports
95
+ `--json` for machine/agent consumption (envelope: `{"ok": true, ...}` on
96
+ success, `{"ok": false, "error": {"code", "message", "action"}}` on
97
+ failure); human-mode errors go to stderr, so stdout is always safe to
98
+ pipe. `db import-keywords`/`db normalize`/`db reindex` mutate the database
99
+ file in place and require `--confirm` (or an interactive yes) — see
100
+ `AGENTS.md` for the backup discipline around them.
101
+
102
+ `search`/`freq`/`stats`/`db ...` work from any directory against one
103
+ machine-wide database — no `bukvarix init` needed. `init`/`status`/`config`
104
+ exist for parity with this CLI's sibling tools (a project can require a
105
+ minimum CLI version via `.bukvarix/config.toml`'s `[cli] min_version`) but
106
+ hold no data bukvarix's own commands read.
107
+
108
+ See `src/bukvarix/data/SKILL.md` for the agent-facing usage guide bundled
109
+ with this package — install it into an AI tool with `bukvarix skill
110
+ install`, or get it as plain text with `bukvarix --ai` (works even without
111
+ file access).
@@ -0,0 +1,184 @@
1
+ [project]
2
+ name = "rb-bukvarix"
3
+ # Version comes from the git tag vX.Y.Z (uv-dynamic-versioning) — never add `version =`.
4
+ dynamic = ["version"]
5
+ description = "Keyword frequencies offline: a local Wordstat-alike over Bukvarix dumps."
6
+ readme = "README.md"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ authors = [{ name = "net.paradox" }]
10
+ requires-python = ">=3.14"
11
+ dependencies = [
12
+ "duckdb>=1.1",
13
+ "pymorphy3>=2.0.6",
14
+ "pymorphy3-dicts-ru>=2.4.417150.4580142",
15
+ "rb-credentials>=0.3,<1",
16
+ "typer>=0.27,<0.29",
17
+ "rich>=13.7",
18
+ "pydantic>=2.6",
19
+ "tomli-w>=1.0",
20
+ "platformdirs>=4.2",
21
+ "packaging>=24.0",
22
+ ]
23
+
24
+ [project.scripts]
25
+ bukvarix = "bukvarix.cli:main"
26
+
27
+ [project.urls]
28
+ Repository = "https://github.com/bolandeu/bukvarix"
29
+
30
+ [build-system]
31
+ requires = ["hatchling", "uv-dynamic-versioning"]
32
+ build-backend = "hatchling.build"
33
+
34
+ [tool.hatch.version]
35
+ source = "uv-dynamic-versioning"
36
+
37
+ [tool.uv-dynamic-versioning]
38
+ vcs = "git"
39
+ style = "pep440"
40
+ fallback-version = "0.0.0"
41
+
42
+ [tool.uv]
43
+ # Rebuild the editable install when a commit or tag moves, so `--version` follows the tag.
44
+ cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]
45
+
46
+ [tool.hatch.build.targets.sdist]
47
+ # What a release must not carry: the agent's own files, the forge configs and the dev tooling. The wheel is
48
+ # narrow already (`packages = ["src/<pkg>"]`); this is about the sdist, which is otherwise a copy of the repo.
49
+ exclude = [
50
+ "/.agents",
51
+ "/.claude",
52
+ "/.claude-plugin",
53
+ "/.gitea",
54
+ "/.github",
55
+ "/docs",
56
+ "/scripts",
57
+ "/uv.lock",
58
+ "/AGENTS.md",
59
+ "/CLAUDE.md",
60
+ "/CODING_STANDARDS.md",
61
+ "/CONTEXT.md",
62
+ "/.copier-answers.yml",
63
+ "^\\.gitignore$",
64
+ "/.gitleaks.toml",
65
+ ]
66
+
67
+ [tool.hatch.build.targets.wheel]
68
+ packages = ["src/bukvarix"]
69
+
70
+ [tool.hatch.build.targets.wheel.force-include]
71
+ # The installed CLI reads [[tool.rb.external]] from here (core/deps.py).
72
+ "pyproject.toml" = "bukvarix/_pyproject.toml"
73
+
74
+ [dependency-groups]
75
+ # Mutation testing, run now and then and before big releases — not in the gate:
76
+ # `uv run --group mutation mutmut run`, then `mutmut results` / `mutmut browse`.
77
+ # Needs fork(): macOS/Linux (WSL on Windows). Settings: [tool.mutmut] below.
78
+ mutation = ["mutmut>=3.3"]
79
+ dev = [
80
+ "jsonschema>=4.23",
81
+ "pytest>=8.0",
82
+ "pyyaml>=6.0", # .copier-answers.yml, the CI workflow, tests/contracts/*.yaml
83
+ "pytest-cov>=5.0",
84
+ "ruff>=0.6",
85
+ "syrupy>=4.8",
86
+ "ty>=0.0.80",
87
+ ]
88
+
89
+ # External (non-Python) dependencies — every CLI this tool runs (require_cli,
90
+ # shutil.which, subprocess with a literal program, npx). The gate checks this
91
+ # list against the code both ways; doctor and require_cli read it at runtime;
92
+ # the tools catalog reads it (the Standard, Technology).
93
+ # [[tool.rb.external]]
94
+ # name = "ffmpeg"
95
+ # required = true # false: the tool works without it (doctor stays healthy)
96
+ # min_version = "6.0" # optional
97
+ # check = "ffmpeg -version" # prints the version; default "<name> --version"
98
+ # why = "transcodes the downloaded videos"
99
+ # detect = false # run via an injected runner / absolute path the gate can't see
100
+ # dist = "rb-serp" # for one of our CLIs: its distribution (default rb-<name>)
101
+ # url = "https://github.com/bolandeu/serp" # its repo: DEPENDENCY_TOO_OLD then prints a pinned install
102
+
103
+ # Where sysadmin's tool-updater installs this tool after its first tag. The
104
+ # installation is sysadmin's; this section only says where. homeserver: users
105
+ # to install for (empty = build and publish only); mac: install on the Mac.
106
+ # extras (optional): the extras to install with, e.g. extras = ["browser"].
107
+ [tool.rb.install]
108
+ homeserver = ["rbtools"]
109
+ mac = true
110
+
111
+ [tool.cli-generator]
112
+ # Where scripts/check_command_docstrings.py (called by the project's checks)
113
+ # looks for commands: a glob or a list of globs, relative to the repo root.
114
+ commands = ["src/bukvarix/commands/*.py"]
115
+ # gate check (the gate): extras to install before ruff/ty/pytest.
116
+ # gate_extras = ["browser"]
117
+
118
+ [tool.pytest.ini_options]
119
+ # Only tests/: mutmut leaves a copy of the tree in mutants/.
120
+ testpaths = ["tests"]
121
+ addopts = "--cov --cov-report=term-missing:skip-covered"
122
+ # tests/test_help.py keeps help snapshots at tests/snapshots/help/<command>.txt
123
+ # (the Standard, Commands), not in syrupy's own `__snapshots__/<test file>/` layout, so
124
+ # syrupy warns it "can not relate" each file to its test. It can — by name.
125
+ filterwarnings = ["ignore:(?s).*Can not relate snapshot:UserWarning"]
126
+
127
+ [tool.mutmut]
128
+ source_paths = ["src/bukvarix"]
129
+ also_copy = ["scripts/", "pyproject.toml"] # tests read them (test_scripts.py, the distribution checks)
130
+ pytest_add_cli_args = ["--no-cov"] # fail_under would kill every mutant
131
+ # only_mutate = ["*/core/normalize.py"] # one module at a time on a big tool
132
+
133
+ [tool.coverage.run]
134
+ source = ["src"]
135
+ # sysmon (default on 3.14) keeps a record per recompiled code object; Typer recompiles annotations on every invoke, so memory grows.
136
+ core = "ctrace"
137
+
138
+ [tool.coverage.report]
139
+ # Keep the bar where it is instead of letting new commands land untested.
140
+ # Raise it, never lower it.
141
+ fail_under = 90
142
+ show_missing = true
143
+
144
+ [tool.ty.terminal]
145
+ # Only errors fail the gate; recent ty (>= 0.0.84) otherwise exits 1 on warnings too.
146
+ # Legacy code that can't be fixed yet: downgrade specific rules instead of
147
+ # ignoring them, e.g. [tool.ty.rules] possibly-unbound-attribute = "warn".
148
+ error-on-warning = false
149
+
150
+ [tool.ruff]
151
+ line-length = 120
152
+ # docs/build.md/AGENTS.md/docs/examples.md embed Python snippets as a historical
153
+ # record of past experiments — ruff's markdown-aware formatter would keep
154
+ # "reformatting" that frozen prose on every run. Format actual source only.
155
+ extend-exclude = ["*.md"]
156
+
157
+ [tool.ruff.lint]
158
+ select = ["E4", "E7", "E9", "F", "I", "UP", "B", "SIM", "RUF", "S", "T20", "TID251"]
159
+ # RUF001-003 flag Cyrillic letters as "ambiguous" vs. Latin look-alikes —
160
+ # meaningless noise for a CLI whose entire domain (stopwords, queries,
161
+ # user-facing strings) is Russian text.
162
+ ignore = ["RUF001", "RUF002", "RUF003"]
163
+
164
+ [tool.ruff.lint.per-file-ignores]
165
+ "tests/*" = ["S101", "T201", "TID251"] # assert is the point of a test; print in code strings; httpx for mocks
166
+ "scripts/*" = ["S603", "S607", "T201"] # subprocess with fixed argv lists (git, uv), no shell; scripts print to the console
167
+ "src/*/providers/*" = ["TID251"] # external APIs live here
168
+ # Dynamic WHERE/column-list SQL built from internal fixed choices (a mode
169
+ # name, a loop index, a stopword list already inserted via `repr()`) and
170
+ # DuckDB `?` placeholders for every actual value — never raw user text.
171
+ "src/bukvarix/core/db.py" = ["S608"]
172
+ "src/bukvarix/core/normalize.py" = ["S608"]
173
+
174
+ [tool.ruff.lint.flake8-tidy-imports.banned-api]
175
+ "httpx".msg = "Call external APIs through providers/ (subclass providers.HttpProvider)."
176
+
177
+ [tool.ruff.lint.flake8-bugbear]
178
+ # Typer's `param: T = typer.Option(...)` style is a call in a default on purpose.
179
+ extend-immutable-calls = ["typer.Option", "typer.Argument"]
180
+
181
+ # Siblings resolve from disk: a version range in `dependencies` plus a `path` source, never an index.
182
+ [tool.uv.sources]
183
+ rb-credentials = { path = "../rb-credentials", editable = true }
184
+
@@ -0,0 +1 @@
1
+ """The package: its modules are the CLI (`cli`), its commands, the output and the core they share."""
@@ -0,0 +1,24 @@
1
+ """The distribution name and the tool namespace copier writes from its answers, because an editable install cannot map
2
+ this import package to its distribution at runtime.
3
+ """
4
+
5
+ # Rendered by copier from the `dist_name` answer: the [project] name in
6
+ # pyproject.toml (`rb-<slug>`, the Standard, Technology), which may differ from this
7
+ # import package's name. importlib.metadata finds this package's version,
8
+ # summary and console script by it; an editable install (`uv sync`) can't be
9
+ # mapped from package to distribution at runtime, so it is written down here.
10
+ # tests/test_cli.py fails if it drifts from pyproject.toml.
11
+ DIST_NAME = "rb-bukvarix"
12
+ # The previous distribution name during a rename: an install made
13
+ # under it (not yet reinstalled) still finds its own version. Drop it once
14
+ # every machine has the new name.
15
+ DIST_NAME_LEGACY: str | None = "bukvarix"
16
+ # The command name (`cli_name`) as an identifier: the namespace of this tool's
17
+ # shared-database names (core/db.py) — table prefix `<TOOL>_`, env var
18
+ # `<TOOL>_DATABASE_URL`, Alembic table `alembic_version_<TOOL>`. Written down,
19
+ # not derived at runtime: a bare source run falls back to the package name,
20
+ # and a table name must never depend on how the tool was started.
21
+ TOOL = "bukvarix"
22
+ # The cli-generator release this project was generated or last updated from
23
+ # (copier's `_commit`), for `describe --json`; None for a project not made by copier.
24
+ TEMPLATE_VERSION: str | None = "v1.27.3"
@@ -0,0 +1,75 @@
1
+ """The root Typer app: global options, the command groups and the optional commands a generated package has, wired
2
+ together, and the console-script entry point.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ import typer
8
+
9
+ from . import output
10
+ from .commands import auth, db, doctor, freq, search, site, stats
11
+ from .core.version import DEV_VERSION, cli_name, installed_version, optional_module, package_summary
12
+
13
+ _PACKAGE_NAME = __name__.split(".")[0]
14
+ # Optional parts (copier questions, dropped by _exclude): each one ships a module that registers its
15
+ # commands and global options. Probed at runtime, so this file needs no template logic.
16
+ PARTS = ("project", "skill", "describe")
17
+
18
+ # A bare `<cli>` is the discovery entry point for humans and agents alike:
19
+ # name + version + description, then every command with the first line of
20
+ # its docstring. No `no_args_is_help` (that exits 2) — main_options() below
21
+ # prints this and exits 0. Shell completion stays enabled.
22
+ app = typer.Typer(
23
+ cls=output.RootGroup, # a usage error under --json is the error envelope
24
+ help=f"{cli_name()} {installed_version() or DEV_VERSION} — {package_summary() or 'Локальный аналог Wordstat поверх дампов ключевых слов Bukvarix'}",
25
+ )
26
+
27
+ app.add_typer(auth.app, name="auth") # `auth status` in every CLI; login/logout only with credentials
28
+ app.add_typer(db.app, name="db")
29
+ app.command(name="doctor")(doctor.doctor)
30
+ app.command(name="search")(search.search)
31
+ app.command(name="freq")(freq.freq)
32
+ app.command(name="site")(site.site)
33
+ app.command(name="stats")(stats.stats)
34
+ for part in PARTS:
35
+ if module := optional_module(f"{_PACKAGE_NAME}.commands.{part}"):
36
+ module.register(app)
37
+
38
+
39
+ def _version_callback(value: bool) -> None:
40
+ if not value:
41
+ return
42
+ typer.echo(installed_version() or DEV_VERSION)
43
+ raise typer.Exit()
44
+
45
+
46
+ @app.callback(invoke_without_command=True)
47
+ def main_options(
48
+ ctx: typer.Context,
49
+ json_output: bool = typer.Option(False, "--json", help="Вывести результат в машиночитаемом формате JSON."),
50
+ quiet: bool = typer.Option(False, "--quiet", help="Подавить второстепенный вывод."),
51
+ verbose: bool = typer.Option(False, "--verbose", help="Вывести дополнительную диагностику."),
52
+ non_interactive: bool = typer.Option(
53
+ False, "--non-interactive", help="Никогда не спрашивать интерактивно — завершаться с ошибкой."
54
+ ),
55
+ dry_run: bool = typer.Option(False, "--dry-run", help="Показать, что произойдёт, без внесения изменений."),
56
+ version: bool = typer.Option(
57
+ False, "--version", callback=_version_callback, is_eager=True, help="Показать версию и выйти."
58
+ ),
59
+ ) -> None:
60
+ ctx.ensure_object(dict) # a part's global option (--project) may have put its value here already
61
+ ctx.obj["json"] = json_output
62
+ ctx.obj["quiet"] = quiet
63
+ ctx.obj["verbose"] = verbose
64
+ ctx.obj["non_interactive"] = non_interactive
65
+ ctx.obj["dry_run"] = dry_run
66
+ output.configure_logging(verbose)
67
+ output.help_if_no_command(ctx)
68
+
69
+
70
+ def main() -> None:
71
+ app()
72
+
73
+
74
+ if __name__ == "__main__":
75
+ main()
@@ -0,0 +1 @@
1
+ """The commands of the CLI, one module per command or command group."""
@@ -0,0 +1,66 @@
1
+ """The `auth` command group: `status` reports the health of the credentials of every provider, or an empty report when
2
+ the package has none.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ import importlib
8
+ from datetime import UTC, datetime
9
+
10
+ import typer
11
+
12
+ from .. import output
13
+ from ..core.errors import InvalidArguments
14
+ from ..core.version import DEV_VERSION, cli_name, installed_version, module_exists, optional_module
15
+
16
+ # `auth status` exists in every CLI (the Standard, Health); a CLI
17
+ # generated without credentials (no credentials/ package, no commands/login.py)
18
+ # reports an empty `credentials` list and exits 0. Detected at runtime so this
19
+ # file needs no template logic — same approach as doctor.py.
20
+ _PACKAGE_NAME = __name__.split(".")[0]
21
+ _HAS_CREDENTIALS = module_exists(f"{_PACKAGE_NAME}.credentials.manager")
22
+
23
+ app = output.group("Credentials: report their health (and store them, if this CLI has any).")
24
+
25
+
26
+ @app.command("status")
27
+ @output.guard
28
+ def auth_status(
29
+ ctx: typer.Context,
30
+ check: bool = typer.Option(
31
+ False, "--check", help="Also make one cheap read-only call per provider (10 s timeout) to prove each works."
32
+ ),
33
+ provider: str | None = typer.Option(
34
+ None, "--provider", help="Report only this provider, or one target as <kind>:<target> (default: all)."
35
+ ),
36
+ json_output: bool = output.JsonOption,
37
+ quiet: bool = output.QuietOption,
38
+ ) -> None:
39
+ """Report every provider's credential: where it comes from and whether it works. Never prints values.
40
+
41
+ Without --check only presence is reported (status `unchecked` or `missing`).
42
+ Exits 0 when every required provider is ok/unchecked (an optional one may be
43
+ missing), 3 when any required provider has a problem or any credential is
44
+ invalid/expired, 2 on a usage error. A per-target provider (one credential per
45
+ site/host/account) gets one entry per stored target, named `<kind>:<target>`. The --json shape is a cross-tool contract:
46
+ `tool`, `version`, `checked_at`, `credentials[]` with `provider`, `required`,
47
+ `fields`, `source`, `source_ref`, `status`, `expires_at`, `quota`, `message`.
48
+
49
+ Example: {cli} auth status --check --json
50
+ """
51
+ tool, version = cli_name(), installed_version() or DEV_VERSION
52
+ if not _HAS_CREDENTIALS:
53
+ if provider is not None:
54
+ raise InvalidArguments(f"Unknown provider '{provider}' ({tool} stores no credentials).")
55
+ checked_at = datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
56
+ payload = {"tool": tool, "version": version, "checked_at": checked_at, "credentials": []}
57
+ output.emit_report(ctx, payload, lambda _: output.human.echo(f"{tool} stores no credentials."), None)
58
+ return
59
+ health = importlib.import_module(f"{_PACKAGE_NAME}.credentials.health")
60
+ payload, problem = health.status(tool, version, check=check, only=provider)
61
+ output.emit_report(ctx, payload, health.render, problem)
62
+
63
+
64
+ if _login := optional_module(f"{_PACKAGE_NAME}.commands.login"):
65
+ app.command("login")(_login.login)
66
+ app.command("logout")(_login.logout)