verkit 0.2.1__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.2.1 → verkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: verkit
-Version: 0.2.1
+Version: 0.3.0
 Summary: Polyglot project version inspector, promoter, tagger, and release workflow engine
 Author: Mark Stouffer
 License: MIT
@@ -122,3 +122,18 @@ $theme = Invoke-RestMethod `
 # $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.2.1 → verkit-0.3.0}/README.md

@@ -112,3 +112,18 @@ $theme = Invoke-RestMethod `
 # $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.2.1 → verkit-0.3.0}/pyproject.toml

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

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.2.1 → 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/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.2.1 → verkit-0.3.0}/uv.lock

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