verkit 0.1.5__tar.gz → 0.3.0__tar.gz

verkit-0.3.0/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+verkit: polyglot version inspector/promoter/tagger, plus shared Rich theme and
+Textual key conventions used by the author's other TUIs.
+
+## Commands
+- Setup: `uv sync`
+- Test: `uv run pytest`
+- Lint: `uv run ruff check .`
+- Release: `verkit release <major|minor|patch>` (do not hand-edit versions)
+
+## Layout
+- `src/verkit/agent_guide.md`: canonical agent conventions (shipped in wheel;
+  printed by `verkit conventions`). Edit here, not in consumers.
+- `src/verkit/keys.py`: `VIM_BINDINGS`. `src/verkit/theme.py` + `theme.json`: theme
+  (kept in sync by `tests/test_theme.py`).
+- `src/verkit/agent.py`: `conventions` / `init-agent` implementation.
+
+## Rules
+- No Textual import in verkit; keep `keys.py` pure data.
+- Changing a convention means updating `agent_guide.md`, `llms.txt`, README, and tests.

verkit-0.3.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

{verkit-0.1.5 → verkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: verkit
-Version: 0.1.5
+Version: 0.3.0
 Summary: Polyglot project version inspector, promoter, tagger, and release workflow engine
 Author: Mark Stouffer
 License: MIT
@@ -86,3 +86,54 @@ tag_name = verkit.tag_version(push=True)
 # 4. Atomic release
 verkit.release_version("patch", push=True)
 ```
+
+---
+
+## Shared Terminal Theme
+
+`verkit` publishes the canonical Rich theme used across this developer's
+CLIs (`task-agent`, `multi-agent-registry`, ...). It is **opt-in** — verkit
+never applies the theme for you; consumers import it and apply it to their
+own `Table`/`Panel` objects:
+
+```python
+from rich.console import Console
+from rich.table import Table
+from verkit.theme import DEFAULT as theme
+
+console = Console()
+table = Table(
+    title="Portfolio",
+    box=theme.table_box,          # borderless
+    header_style=theme.header_style,  # "on grey23"
+    padding=theme.table_padding,  # (0, 2, 0, 0)
+)
+console.print(table)
+```
+
+The theme is a frozen dataclass (`verkit.theme.Theme`); `DEFAULT` is the
+canonical instance. Non-Python consumers (e.g. PowerShell scripts) read the
+machine-readable mirror, which stays in sync via `tests/test_theme.py`:
+
+```powershell
+$theme = Invoke-RestMethod `
+  https://raw.githubusercontent.com/bizkite-co/verkit/main/src/verkit/theme.json
+# $theme.theme.header_style               -> "on grey23"
+# $theme.theme.header_background_ansi     -> ANSI 256 index 237 background escape
+# $theme.theme.header_background_rgb_hex  -> "#3a3a3a"
+```
+
+---
+
+## For AI Agents
+
+Projects that depend on `verkit` should follow its conventions: vim-style
+navigation (`from verkit.keys import VIM_BINDINGS`), the shared theme, and a
+`mise`-only local dev override (PyPI release everywhere else).
+
+```bash
+verkit conventions          # print the guide (add --json for structured output)
+verkit init-agent --mise    # add pointer to AGENTS.md and a mise.toml template
+```
+
+See also `AGENTS.md` and `llms.txt` in this repo.

{verkit-0.1.5 → verkit-0.3.0}/README.md

@@ -76,3 +76,54 @@ tag_name = verkit.tag_version(push=True)
 # 4. Atomic release
 verkit.release_version("patch", push=True)
 ```
+
+---
+
+## Shared Terminal Theme
+
+`verkit` publishes the canonical Rich theme used across this developer's
+CLIs (`task-agent`, `multi-agent-registry`, ...). It is **opt-in** — verkit
+never applies the theme for you; consumers import it and apply it to their
+own `Table`/`Panel` objects:
+
+```python
+from rich.console import Console
+from rich.table import Table
+from verkit.theme import DEFAULT as theme
+
+console = Console()
+table = Table(
+    title="Portfolio",
+    box=theme.table_box,          # borderless
+    header_style=theme.header_style,  # "on grey23"
+    padding=theme.table_padding,  # (0, 2, 0, 0)
+)
+console.print(table)
+```
+
+The theme is a frozen dataclass (`verkit.theme.Theme`); `DEFAULT` is the
+canonical instance. Non-Python consumers (e.g. PowerShell scripts) read the
+machine-readable mirror, which stays in sync via `tests/test_theme.py`:
+
+```powershell
+$theme = Invoke-RestMethod `
+  https://raw.githubusercontent.com/bizkite-co/verkit/main/src/verkit/theme.json
+# $theme.theme.header_style               -> "on grey23"
+# $theme.theme.header_background_ansi     -> ANSI 256 index 237 background escape
+# $theme.theme.header_background_rgb_hex  -> "#3a3a3a"
+```
+
+---
+
+## For AI Agents
+
+Projects that depend on `verkit` should follow its conventions: vim-style
+navigation (`from verkit.keys import VIM_BINDINGS`), the shared theme, and a
+`mise`-only local dev override (PyPI release everywhere else).
+
+```bash
+verkit conventions          # print the guide (add --json for structured output)
+verkit init-agent --mise    # add pointer to AGENTS.md and a mise.toml template
+```
+
+See also `AGENTS.md` and `llms.txt` in this repo.

verkit-0.3.0/llms.txt

@@ -0,0 +1,15 @@
+# verkit
+
+> Polyglot project version inspector, promoter, tagger and release CLI, plus the shared Rich theme and vim-style Textual key conventions for the author's Python TUIs. If your project depends on verkit, read the conventions guide first.
+
+## Agent guidance
+- [Conventions guide](https://raw.githubusercontent.com/bizkite-co/verkit/main/src/verkit/agent_guide.md): vim navigation, theme, mise dev-vs-PyPI rule. Also `verkit conventions [--json]`.
+- [AGENTS.md](https://raw.githubusercontent.com/bizkite-co/verkit/main/AGENTS.md): working on verkit itself.
+
+## Code
+- [keys.py](https://raw.githubusercontent.com/bizkite-co/verkit/main/src/verkit/keys.py): `VIM_BINDINGS` for Textual `BINDINGS`.
+- [theme.py](https://raw.githubusercontent.com/bizkite-co/verkit/main/src/verkit/theme.py): shared Rich theme.
+- [theme.json](https://raw.githubusercontent.com/bizkite-co/verkit/main/src/verkit/theme.json): theme for non-Python consumers.
+
+## Optional
+- [README](https://raw.githubusercontent.com/bizkite-co/verkit/main/README.md): CLI and API usage.

{verkit-0.1.5 → verkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "verkit"
-version = "0.1.5"
+version = "0.3.0"
 description = "Polyglot project version inspector, promoter, tagger, and release workflow engine"
 readme = "README.md"
 requires-python = ">=3.9"

{verkit-0.1.5 → verkit-0.3.0}/src/verkit/__init__.py

@@ -10,16 +10,19 @@ from verkit.inspector import (
 )
 from verkit.promoter import promote_version
 from verkit.tagger import release_version, tag_version
+from verkit.theme import DEFAULT, Theme
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 __all__ = [
+    "DEFAULT",
+    "Theme",
     "VersionInfo",
-    "inspect_project",
-    "inspect_committed",
+    "display_version_info",
     "get_installed_version",
     "get_latest_pypi_version",
-    "display_version_info",
+    "inspect_committed",
+    "inspect_project",
     "promote_version",
-    "tag_version",
     "release_version",
+    "tag_version",
 ]

verkit-0.3.0/src/verkit/agent.py

@@ -0,0 +1,75 @@
+"""Agent-facing commands: print conventions and wire them into a project."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from pathlib import Path
+
+from verkit.keys import VIM_BINDINGS
+
+MARKER = "<!-- verkit:agent-guide -->"
+
+SNIPPET = f"""{MARKER}
+## verkit conventions
+
+This project depends on `verkit`. Before touching TUI, theme, or dev-setup
+code, run `verkit conventions` (or read `verkit/agent_guide.md` in the
+installed package). Key rules: vim-style navigation via
+`verkit.keys.VIM_BINDINGS`, shared theme via `verkit.theme`, and local verkit
+dev override through `mise` only (never in `pyproject.toml`).
+"""
+
+MISE_TEMPLATE = """# Generated by `verkit init-agent --mise`.
+# Local checkout of verkit is used when it exists; CI/Docker/users get PyPI.
+[env]
+VERKIT_DEV = "{{ env.HOME }}/repos/verkit"
+UV_NO_SYNC = "1"   # keep uv from replacing the editable install with PyPI's
+
+[tasks.install]
+run = '''
+uv sync
+if [ -d "$VERKIT_DEV" ]; then uv pip install -e "$VERKIT_DEV"; fi
+'''
+"""
+
+
+def guide_text() -> str:
+    return resources.files("verkit").joinpath("agent_guide.md").read_text(encoding="utf-8")
+
+
+def conventions_json() -> str:
+    return json.dumps(
+        {
+            "vim_bindings": [
+                {"key": k, "action": a, "description": d} for k, a, d in VIM_BINDINGS
+            ],
+            "import": "from verkit.keys import VIM_BINDINGS",
+            "theme_import": "from verkit.theme import DEFAULT as theme",
+            "dev_override": "mise.toml only; never pyproject.toml",
+            "guide": guide_text(),
+        },
+        indent=2,
+    )
+
+
+def init_agent(directory: Path, mise: bool = False) -> list[str]:
+    """Idempotently add the pointer to AGENTS.md (and mise.toml if asked)."""
+    changed: list[str] = []
+    agents = directory / "AGENTS.md"
+    existing = agents.read_text(encoding="utf-8") if agents.exists() else ""
+    if MARKER not in existing:
+        sep = "\n" if existing and not existing.endswith("\n\n") else ""
+        agents.write_text(existing + sep + SNIPPET, encoding="utf-8")
+        changed.append(str(agents))
+    if mise:
+        target = directory / "mise.toml"
+        present = [f for f in (target, directory / "mise.verkit.toml") if f.exists()]
+        if any("VERKIT_DEV" in f.read_text(encoding="utf-8") for f in present):
+            return changed
+        if target.exists():
+            target = directory / "mise.verkit.toml"  # never clobber; merge by hand
+        if not target.exists():
+            target.write_text(MISE_TEMPLATE, encoding="utf-8")
+            changed.append(str(target))
+    return changed

verkit-0.3.0/src/verkit/agent_guide.md

@@ -0,0 +1,63 @@
+# verkit conventions for AI agents
+
+verkit is the shared foundation for this developer's Python Textual/Rich TUIs
+and CLIs. If the project you are working in depends on `verkit`, follow these
+conventions. Print this guide any time with `verkit conventions`.
+
+## 1. Vim-style navigation (required for every TUI)
+
+Every Textual TUI must support vim-style navigation **in addition to** the
+arrow keys, never instead of them.
+
+| Key | Action | Textual action |
+| :-- | :-- | :-- |
+| `j` / `k` | move down / up | `cursor_down` / `cursor_up` |
+| `h` / `l` | move left / right | `cursor_left` / `cursor_right` |
+| `g` / `G` | jump to top / bottom | `scroll_home` / `scroll_end` |
+| `ctrl+d` / `ctrl+u` | half-page down / up | `page_down` / `page_up` |
+| `/` | search / filter | app-specific |
+| `escape` | go back / close | app-specific |
+| `q` | quit | `quit` |
+
+Do not hand-write these. Import them:
+
+```python
+from verkit.keys import VIM_BINDINGS
+
+class MyApp(App):
+    BINDINGS = [*VIM_BINDINGS, ("f", "filter", "Filter")]
+```
+
+Show bindings in the `Footer`. Do not reassign these keys to other meanings.
+
+## 2. Theme
+
+Use the shared Rich theme; never copy-paste style constants:
+
+```python
+from verkit.theme import DEFAULT as theme
+```
+
+Machine-readable mirror for non-Python consumers: `theme.json` in the package.
+
+## 3. Dev vs. released verkit (mise)
+
+Rule: **in the local checkout, run the local verkit source; everywhere else
+(CI, Docker, end users) install the latest release from PyPI.**
+
+- `pyproject.toml` declares a plain dependency (`"verkit"`). Never add a
+  `path`/`editable` source there: it would leak to CI and to PyPI consumers.
+- Local override lives only in the consumer's `mise.toml`, and is a no-op when
+  the local verkit checkout does not exist. Generate it with
+  `verkit init-agent --mise`. It sets `VERKIT_DEV` (default
+  `~/repos/verkit`) and installs it editable after `uv sync`.
+- Use `mise run install` (not bare `uv sync`), and run tools with
+  `UV_NO_SYNC=1` (set by the mise template) so uv does not replace the
+  editable install with the PyPI release.
+
+## 4. Agent-friendly CLI
+
+- `verkit conventions [--json]` prints this guide (or structured JSON).
+- `verkit init-agent [--mise] [--dir PATH]` adds a pointer to this guide in the
+  project's `AGENTS.md` (idempotent) and, with `--mise`, writes the mise template.
+- Errors exit non-zero, so agents can rely on exit codes.

{verkit-0.1.5 → verkit-0.3.0}/src/verkit/cli.py

@@ -1,8 +1,10 @@
 import argparse
 import sys
+from pathlib import Path
 
 from rich.console import Console
 
+from verkit.agent import conventions_json, guide_text, init_agent
 from verkit.inspector import display_version_info
 from verkit.promoter import promote_version
 from verkit.tagger import release_version, tag_version
@@ -47,6 +49,15 @@ def main():
         help="Promote and tag locally only",
     )
 
+    # verkit conventions [--json]
+    conv_p = subparsers.add_parser("conventions", help="Print conventions for AI agents")
+    conv_p.add_argument("--json", action="store_true", help="Structured output")
+
+    # verkit init-agent
+    init_p = subparsers.add_parser("init-agent", help="Add verkit guidance to a project")
+    init_p.add_argument("--dir", default=".", help="Project directory")
+    init_p.add_argument("--mise", action="store_true", help="Also write mise.toml template")
+
     args = parser.parse_args()
     console = Console()
 
@@ -55,7 +66,12 @@ def main():
         return
 
     try:
-        if args.command == "promote":
+        if args.command == "conventions":
+            print(conventions_json() if args.json else guide_text())
+        elif args.command == "init-agent":
+            changed = init_agent(Path(args.dir), mise=args.mise)
+            console.print("\n".join(f"updated {c}" for c in changed) or "already up to date")
+        elif args.command == "promote":
             promote_version(args.part, console=console, allow_amend=getattr(args, "allow_amend", True))
         elif args.command == "tag":
             tag_version(console=console, push=getattr(args, "push", True))

verkit-0.3.0/src/verkit/keys.py

@@ -0,0 +1,29 @@
+"""Canonical vim-style key bindings for Textual TUIs.
+
+Pure data with no Textual import, so verkit does not depend on Textual.
+Entries are ``(key, action, description)`` tuples, which is what Textual's
+``BINDINGS`` accepts directly::
+
+    from verkit.keys import VIM_BINDINGS
+
+    class MyApp(App):
+        BINDINGS = [*VIM_BINDINGS, ("f", "filter", "Filter")]
+
+Arrow keys keep working through Textual's defaults; these add the vim keys.
+"""
+
+from __future__ import annotations
+
+VIM_BINDINGS: list[tuple[str, str, str]] = [
+    ("j", "cursor_down", "Down"),
+    ("k", "cursor_up", "Up"),
+    ("h", "cursor_left", "Left"),
+    ("l", "cursor_right", "Right"),
+    ("g", "scroll_home", "Top"),
+    ("G", "scroll_end", "Bottom"),
+    ("ctrl+d", "page_down", "Page down"),
+    ("ctrl+u", "page_up", "Page up"),
+    ("q", "quit", "Quit"),
+]
+
+__all__ = ["VIM_BINDINGS"]

verkit-0.3.0/src/verkit/theme.json

@@ -0,0 +1,18 @@
+{
+  "name": "verkit-grey",
+  "version": 1,
+  "description": "Shared Rich terminal theme for tables and panels across this developer's Python CLIs (task-agent, multi-agent-registry, ...). Source of truth is src/verkit/theme.py (the Theme dataclass); this JSON mirrors Theme.DEFAULT for non-Python consumers and is kept in sync by tests/test_theme.py.",
+  "adoption": {
+    "python": "from verkit.theme import DEFAULT as theme",
+    "powershell": "$theme = Invoke-RestMethod '<raw URL of this file>'; $theme.theme",
+    "note": "Opt-in only: verkit publishes the theme but never applies it for you."
+  },
+  "theme": {
+    "table_box": null,
+    "panel_box": "MINIMAL",
+    "table_padding": [0, 2, 0, 0],
+    "header_style": "on grey23",
+    "header_background_ansi": "\u001b[48;5;237m",
+    "header_background_rgb_hex": "#3a3a3a"
+  }
+}

verkit-0.3.0/src/verkit/theme.py

@@ -0,0 +1,55 @@
+"""Shared visual theme for Rich terminal output across client CLIs.
+
+This module is a *convention carrier*, not a mandate. The theme is published
+here so a client project can opt in with a one-line import instead of
+maintaining its own copy; importing it is never forced on consumers.
+
+Adoption hint (Python)::
+
+    from verkit.theme import DEFAULT as theme
+
+    table = Table(
+        title="...",
+        box=theme.table_box,
+        header_style=theme.header_style,
+        padding=theme.table_padding,
+    )
+    console.print(Panel(..., box=theme.panel_box))
+
+Because ``Theme`` is a frozen dataclass, ``DEFAULT`` can be shared or
+subclassed without risk of accidental mutation.
+
+Non-Python consumers (e.g. PowerShell scripts) should read the machine
+readable mirror at ``src/verkit/theme.json`` instead of re-deriving styles:
+
+    $theme = Invoke-RestMethod `
+      https://raw.githubusercontent.com/bizkite-co/verkit/main/src/verkit/theme.json
+
+The JSON and this dataclass are kept in sync by ``tests/test_theme.py``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rich import box as rich_box
+
+
+@dataclass(frozen=True)
+class Theme:
+    """Visual theme for Rich terminal output (tables, panels).
+
+    Defaults render tables and panels in the compact report style shared
+    across this developer's CLIs: borderless tables, a minimal panel border,
+    and a subtle grey header band (ANSI 256 index 237).
+    """
+
+    table_box: rich_box.Box | None = None
+    panel_box: rich_box.Box = rich_box.MINIMAL
+    table_padding: tuple[int, int, int, int] = (0, 2, 0, 0)
+    header_style: str = "on grey23"
+
+
+#: The canonical theme. Client CLIs opt in with ``from verkit.theme import
+#: DEFAULT``.
+DEFAULT = Theme()

verkit-0.3.0/tests/test_agent.py

@@ -0,0 +1,30 @@
+import json
+
+from verkit.agent import MARKER, conventions_json, guide_text, init_agent
+from verkit.keys import VIM_BINDINGS
+
+
+def test_guide_mentions_bindings_and_mise():
+    g = guide_text()
+    assert "VIM_BINDINGS" in g and "mise" in g
+
+
+def test_bindings_shape_and_vim_keys():
+    assert all(len(b) == 3 for b in VIM_BINDINGS)
+    assert {"j", "k", "h", "l"} <= {b[0] for b in VIM_BINDINGS}
+
+
+def test_json_output():
+    data = json.loads(conventions_json())
+    assert data["vim_bindings"][0]["key"] == "j"
+
+
+def test_init_agent_idempotent_and_no_clobber(tmp_path):
+    (tmp_path / "AGENTS.md").write_text("# Mine\n")
+    assert init_agent(tmp_path, mise=True)
+    assert init_agent(tmp_path, mise=True) == []
+    text = (tmp_path / "AGENTS.md").read_text()
+    assert text.startswith("# Mine") and text.count(MARKER) == 1
+    (tmp_path / "mise.toml").write_text("[tools]\n")
+    init_agent(tmp_path, mise=True)
+    assert (tmp_path / "mise.toml").read_text() == "[tools]\n"

verkit-0.3.0/tests/test_theme.py

@@ -0,0 +1,38 @@
+import json
+from pathlib import Path
+
+from rich import box as rich_box
+
+from verkit.theme import DEFAULT, Theme
+
+THEME_JSON = Path(__file__).resolve().parent.parent / "src" / "verkit" / "theme.json"
+
+
+def test_default_is_theme():
+    assert isinstance(DEFAULT, Theme)
+
+
+def test_default_values():
+    assert DEFAULT.table_box is None
+    assert DEFAULT.panel_box is rich_box.MINIMAL
+    assert DEFAULT.table_padding == (0, 2, 0, 0)
+    assert DEFAULT.header_style == "on grey23"
+
+
+def test_theme_json_matches_default():
+    data = json.loads(THEME_JSON.read_text(encoding="utf-8"))
+    theme = data["theme"]
+    assert theme["table_box"] is None
+    assert theme["panel_box"] == "MINIMAL"
+    assert tuple(theme["table_padding"]) == DEFAULT.table_padding
+    assert theme["header_style"] == DEFAULT.header_style
+    assert theme["header_background_ansi"] == "\x1b[48;5;237m"
+
+
+def test_theme_is_frozen():
+    try:
+        DEFAULT.table_padding = (1, 1, 1, 1)
+    except AttributeError:
+        pass
+    else:
+        raise AssertionError("Theme should be immutable")

{verkit-0.1.5 → verkit-0.3.0}/uv.lock

@@ -70,7 +70,7 @@ wheels = [
 
 [[package]]
 name = "verkit"
-version = "0.1.4"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "rich" },