verkit 0.1.1__tar.gz

verkit-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      # https://github.com/actions/checkout
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      # https://github.com/astral-sh/setup-uv
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+      - name: Run mypy
+        run: uv run mypy src

verkit-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+      attestations: write
+
+    steps:
+      # https://github.com/actions/checkout
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      # https://github.com/astral-sh/setup-uv
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true

verkit-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/
+build/
+*.egg-info/

verkit-0.1.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: verkit
+Version: 0.1.1
+Summary: Polyglot project version inspector, promoter, tagger, and release workflow engine
+Author: Mark Stouffer
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: rich>=10.0.0
+Description-Content-Type: text/markdown
+
+# verkit
+
+Polyglot project version inspector, promoter, tagger, and release workflow engine.
+
+`verkit` provides a unified Python API and CLI tool to manage version releases across multi-language projects (`pyproject.toml`, `package.json`, `Cargo.toml`, `*.csproj`, `pom.xml`, `build.gradle`).
+
+---
+
+## Supported Ecosystems
+| Project Type | Version File | Parser / Bump Engine |
+| :--- | :--- | :--- |
+| **Python** | `pyproject.toml` | Regex & `bump-my-version` |
+| **Node.js** | `package.json` | JSON parser & `npm version` |
+| **Rust** | `Cargo.toml` | Regex (`^version = "..."`) |
+| **.NET** | `*.csproj` | XML Regex (`<Version>...</Version>`) |
+| **Java (Maven)** | `pom.xml` | XML Regex (`<version>...</version>`) |
+| **Java (Gradle)** | `build.gradle` / `.kts` | Regex (`version = "..."`) |
+
+---
+
+## Installation
+```bash
+pip install verkit
+# or using uv
+uv add verkit
+```
+
+---
+
+## CLI Usage
+
+### Inspect version info
+Inspect current working tree and HEAD committed versions:
+```bash
+verkit inspect
+```
+
+### Promote version
+Bump version (`major`, `minor`, or `patch`) and automatically commit or amend local release commit:
+```bash
+verkit promote minor
+```
+
+### Tag and push release
+Verify HEAD is in sync, create `vX.Y.Z` git tag, and push branch + tag:
+```bash
+verkit tag
+```
+
+### One-shot atomic release
+Combine promote, tag, and push in a single step:
+```bash
+verkit release patch
+```
+
+---
+
+## Python API Usage
+
+```python
+import verkit
+
+# 1. Inspect version info
+info = verkit.inspect_project()
+print(f"Working version: {info.version} (from {info.source})")
+
+committed = verkit.inspect_committed()
+print(f"HEAD committed version: {committed.version}")
+
+# 2. Promote version
+new_version = verkit.promote_version("minor")
+
+# 3. Tag and push release
+tag_name = verkit.tag_version(push=True)
+
+# 4. Atomic release
+verkit.release_version("patch", push=True)
+```

verkit-0.1.1/README.md

@@ -0,0 +1,78 @@
+# verkit
+
+Polyglot project version inspector, promoter, tagger, and release workflow engine.
+
+`verkit` provides a unified Python API and CLI tool to manage version releases across multi-language projects (`pyproject.toml`, `package.json`, `Cargo.toml`, `*.csproj`, `pom.xml`, `build.gradle`).
+
+---
+
+## Supported Ecosystems
+| Project Type | Version File | Parser / Bump Engine |
+| :--- | :--- | :--- |
+| **Python** | `pyproject.toml` | Regex & `bump-my-version` |
+| **Node.js** | `package.json` | JSON parser & `npm version` |
+| **Rust** | `Cargo.toml` | Regex (`^version = "..."`) |
+| **.NET** | `*.csproj` | XML Regex (`<Version>...</Version>`) |
+| **Java (Maven)** | `pom.xml` | XML Regex (`<version>...</version>`) |
+| **Java (Gradle)** | `build.gradle` / `.kts` | Regex (`version = "..."`) |
+
+---
+
+## Installation
+```bash
+pip install verkit
+# or using uv
+uv add verkit
+```
+
+---
+
+## CLI Usage
+
+### Inspect version info
+Inspect current working tree and HEAD committed versions:
+```bash
+verkit inspect
+```
+
+### Promote version
+Bump version (`major`, `minor`, or `patch`) and automatically commit or amend local release commit:
+```bash
+verkit promote minor
+```
+
+### Tag and push release
+Verify HEAD is in sync, create `vX.Y.Z` git tag, and push branch + tag:
+```bash
+verkit tag
+```
+
+### One-shot atomic release
+Combine promote, tag, and push in a single step:
+```bash
+verkit release patch
+```
+
+---
+
+## Python API Usage
+
+```python
+import verkit
+
+# 1. Inspect version info
+info = verkit.inspect_project()
+print(f"Working version: {info.version} (from {info.source})")
+
+committed = verkit.inspect_committed()
+print(f"HEAD committed version: {committed.version}")
+
+# 2. Promote version
+new_version = verkit.promote_version("minor")
+
+# 3. Tag and push release
+tag_name = verkit.tag_version(push=True)
+
+# 4. Atomic release
+verkit.release_version("patch", push=True)
+```

verkit-0.1.1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "verkit"
+version = "0.1.1"
+description = "Polyglot project version inspector, promoter, tagger, and release workflow engine"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Mark Stouffer" }
+]
+dependencies = [
+    "rich>=10.0.0",
+]
+
+[project.scripts]
+verkit = "verkit.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

verkit-0.1.1/src/verkit/__init__.py

@@ -0,0 +1,14 @@
+"""Polyglot project version inspector, promoter, tagger, and release engine."""
+
+from verkit.inspector import VersionInfo, inspect_project, inspect_committed
+from verkit.promoter import promote_version
+from verkit.tagger import tag_version
+
+__version__ = "0.1.0"
+__all__ = [
+    "VersionInfo",
+    "inspect_project",
+    "inspect_committed",
+    "promote_version",
+    "tag_version",
+]

verkit-0.1.1/src/verkit/cli.py

@@ -0,0 +1,73 @@
+import argparse
+import sys
+
+from rich.console import Console
+
+from verkit.inspector import inspect_committed, inspect_project
+from verkit.promoter import promote_version
+from verkit.tagger import release_version, tag_version
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="verkit",
+        description="Polyglot project version inspector, promoter, tagger, and release workflow tool",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Subcommand to run")
+
+    # verkit inspect
+    subparsers.add_parser("inspect", help="Inspect working tree and HEAD version")
+
+    # verkit promote <major|minor|patch>
+    promote_p = subparsers.add_parser("promote", help="Bump version and commit/amend")
+    promote_p.add_argument("part", choices=["major", "minor", "patch"])
+    promote_p.add_argument(
+        "--no-amend",
+        dest="allow_amend",
+        action="store_false",
+        help="Always create a new commit",
+    )
+
+    # verkit tag
+    tag_p = subparsers.add_parser("tag", help="Create git tag on HEAD and push")
+    tag_p.add_argument(
+        "--no-push",
+        dest="push",
+        action="store_false",
+        help="Skip pushing to origin",
+    )
+
+    # verkit release <major|minor|patch>
+    rel_p = subparsers.add_parser("release", help="Atomic promote + tag + push")
+    rel_p.add_argument("part", choices=["major", "minor", "patch"])
+    rel_p.add_argument(
+        "--no-push",
+        dest="push",
+        action="store_false",
+        help="Promote and tag locally only",
+    )
+
+    args = parser.parse_args()
+    console = Console()
+
+    if not args.command or args.command == "inspect":
+        info = inspect_project()
+        committed = inspect_committed()
+        console.print(f"[bold blue]Working version:[/bold blue] {info.version} (from {info.source or 'unknown'})")
+        console.print(f"[dim]Committed version (HEAD):[/dim] {committed.version}")
+        return
+
+    try:
+        if 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))
+        elif args.command == "release":
+            release_version(args.part, console=console, push=getattr(args, "push", True))
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

verkit-0.1.1/src/verkit/inspector.py

@@ -0,0 +1,142 @@
+import json
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class VersionInfo:
+    version: str
+    source: Optional[str] = None
+
+
+def get_project_version(root: Optional[Path] = None) -> VersionInfo:
+    """Read the current project version from various project files (working tree)."""
+    root = root or Path.cwd()
+
+    # Check pyproject.toml
+    pyproject = root / "pyproject.toml"
+    if pyproject.exists():
+        try:
+            with pyproject.open("r", encoding="utf-8") as f:
+                content = f.read()
+                match = re.search(r'version\s*=\s*"(.*?)"', content)
+                if match:
+                    return VersionInfo(version=match.group(1), source="pyproject.toml")
+        except Exception:
+            pass
+
+    # Check package.json
+    package_json = root / "package.json"
+    if package_json.exists():
+        try:
+            with package_json.open("r", encoding="utf-8") as f:
+                data = json.load(f)
+                if "version" in data:
+                    return VersionInfo(version=data["version"], source="package.json")
+        except Exception:
+            pass
+
+    # Check Cargo.toml (Rust)
+    cargo = root / "Cargo.toml"
+    if cargo.exists():
+        try:
+            with cargo.open("r", encoding="utf-8") as f:
+                content = f.read()
+                match = re.search(r'^version\s*=\s*"(.*?)"', content, re.MULTILINE)
+                if match:
+                    return VersionInfo(version=match.group(1), source="Cargo.toml")
+        except Exception:
+            pass
+
+    # Check *.csproj (.NET)
+    for csproj in root.glob("*.csproj"):
+        try:
+            with csproj.open("r", encoding="utf-8") as f:
+                content = f.read()
+                match = re.search(r"<Version>(.*?)</Version>", content)
+                if match:
+                    return VersionInfo(version=match.group(1), source=csproj.name)
+        except Exception:
+            pass
+
+    # Check pom.xml (Java/Maven)
+    pom = root / "pom.xml"
+    if pom.exists():
+        try:
+            with pom.open("r", encoding="utf-8") as f:
+                content = f.read()
+                match = re.search(r"<version>(.*?)</version>", content)
+                if match:
+                    return VersionInfo(version=match.group(1), source="pom.xml")
+        except Exception:
+            pass
+
+    # Check build.gradle (Java/Gradle)
+    gradle_kts = root / "build.gradle.kts"
+    gradle = root / "build.gradle"
+    gradle_file = None
+    if gradle_kts.exists():
+        gradle_file = gradle_kts
+    elif gradle.exists():
+        gradle_file = gradle
+
+    if gradle_file:
+        try:
+            with gradle_file.open("r", encoding="utf-8") as f:
+                content = f.read()
+                match = re.search(r'version\s*=\s*["\'](.*?)["\']', content)
+                if match:
+                    return VersionInfo(version=match.group(1), source=gradle_file.name)
+        except Exception:
+            pass
+
+    return VersionInfo(version="unknown", source=None)
+
+
+def inspect_project(root: Optional[Path] = None) -> VersionInfo:
+    return get_project_version(root)
+
+
+def inspect_committed(root: Optional[Path] = None) -> VersionInfo:
+    """Read the version from HEAD (committed code), not working tree."""
+    files_to_check = [
+        ("pyproject.toml", r'version\s*=\s*"(.*?)"'),
+        ("package.json", None),
+        ("Cargo.toml", r'^version\s*=\s*"(.*?)"'),
+    ]
+
+    git_c = ["git"]
+    if root is not None:
+        git_c = ["git", "-C", str(root)]
+
+    for filename, pattern in files_to_check:
+        try:
+            result = subprocess.run(
+                git_c + ["show", f"HEAD:{filename}"],
+                capture_output=True,
+                text=True,
+                check=False,
+                shell=(os.name == "nt"),
+            )
+            if result.returncode == 0:
+                if filename == "package.json":
+                    try:
+                        data = json.loads(result.stdout)
+                        if "version" in data:
+                            return VersionInfo(
+                                version=data["version"], source="package.json"
+                            )
+                    except Exception:
+                        pass
+                elif pattern:
+                    match = re.search(pattern, result.stdout, re.MULTILINE)
+                    if match:
+                        return VersionInfo(version=match.group(1), source=filename)
+        except Exception:
+            pass
+
+    return VersionInfo(version="unknown", source=None)

verkit-0.1.1/src/verkit/promoter.py

@@ -0,0 +1,305 @@
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from rich.console import Console
+
+from verkit.inspector import get_project_version, inspect_committed
+
+_VERSION_FILES = ("pyproject.toml", "package.json", "uv.lock", "Cargo.toml")
+
+
+def _git(*args: str, cwd: Optional[Path] = None) -> subprocess.CompletedProcess:
+    cmd = ["git"]
+    if cwd is not None:
+        cmd += ["-C", str(cwd)]
+    cmd.extend(args)
+    return subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=False,
+        shell=(os.name == "nt"),
+    )
+
+
+def _find_git_root(path: Path) -> Optional[Path]:
+    res = _git("rev-parse", "--show-toplevel", cwd=path)
+    if res.returncode == 0 and res.stdout.strip():
+        return Path(res.stdout.strip()).resolve()
+    return None
+
+
+def _can_amend_version_safely(git_root: Path) -> Tuple[bool, str]:
+    """Whether folding the version bump into HEAD via amend is safe."""
+    res = _git("rev-parse", "HEAD", cwd=git_root)
+    if res.returncode != 0 or not res.stdout.strip():
+        return False, "no HEAD commit"
+
+    tags_res = _git(
+        "tag", "--points-at", "HEAD", "--format=%(refname:short)", cwd=git_root
+    )
+    if tags_res.returncode == 0 and tags_res.stdout.strip():
+        tags = [t for t in tags_res.stdout.strip().splitlines() if t]
+        return False, f"HEAD is tagged ({', '.join(tags)})"
+
+    branch_res = _git("rev-parse", "--abbrev-ref", "HEAD", cwd=git_root)
+    branch = branch_res.stdout.strip() if branch_res.returncode == 0 else ""
+    if not branch or branch == "HEAD":
+        return False, "detached HEAD"
+
+    upstream_res = _git(
+        "rev-parse", "--abbrev-ref", "@{upstream}", cwd=git_root
+    )
+    if upstream_res.returncode != 0 or not upstream_res.stdout.strip():
+        return True, "local branch has no tracking upstream"
+    upstream = upstream_res.stdout.strip()
+
+    counts = _git(
+        "rev-list", "--count", f"{upstream}..HEAD", cwd=git_root
+    )
+    if counts.returncode != 0:
+        return False, f"could not compare HEAD to {upstream}"
+    try:
+        ahead = int(counts.stdout.strip())
+    except ValueError:
+        return False, "invalid rev-list output"
+
+    if ahead <= 0:
+        return (
+            False,
+            f"HEAD is already published to {upstream} (ahead count: {ahead})",
+        )
+    return True, f"HEAD is ahead of {upstream} by {ahead} unpushed commit(s)"
+
+
+def _stage_version_files(git_root: Path, project_root: Path) -> List[str]:
+    staged: List[str] = []
+    for name in _VERSION_FILES:
+        target = project_root / name
+        if target.exists():
+            res = _git("add", str(target), cwd=git_root)
+            if res.returncode == 0:
+                try:
+                    rel = str(target.relative_to(git_root))
+                except ValueError:
+                    rel = name
+                staged.append(rel)
+    return staged
+
+
+def _increment_semver(current_v: str, part: str) -> str:
+    """Increment a semver string (e.g. 0.1.0 -> 0.1.1) in pure Python."""
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)(.*)$", current_v.strip())
+    if not match:
+        raise ValueError(f"Version {current_v!r} is not a valid semver X.Y.Z string")
+
+    major, minor, patch, extra = (
+        int(match.group(1)),
+        int(match.group(2)),
+        int(match.group(3)),
+        match.group(4),
+    )
+    if part == "major":
+        major += 1
+        minor = 0
+        patch = 0
+    elif part == "minor":
+        minor += 1
+        patch = 0
+    elif part == "patch":
+        patch += 1
+    else:
+        raise ValueError(f"Unknown bump part: {part!r}")
+
+    return f"{major}.{minor}.{patch}{extra}"
+
+
+def _bump_project_version(part: str, project_root: Path, source: str) -> str:
+    info = get_project_version(project_root)
+    if info.version == "unknown":
+        raise RuntimeError("Cannot bump version: current project version is unknown.")
+
+    new_v = _increment_semver(info.version, part)
+
+    if source == "pyproject.toml":
+        file_path = project_root / "pyproject.toml"
+        content = file_path.read_text(encoding="utf-8")
+        updated = re.sub(
+            r'(version\s*=\s*)"(.*?)"', f'\\1"{new_v}"', content, count=1
+        )
+        file_path.write_text(updated, encoding="utf-8")
+
+        # Also sync uv.lock if present
+        uv_lock = project_root / "uv.lock"
+        if uv_lock.exists():
+            try:
+                lock_text = uv_lock.read_text(encoding="utf-8")
+                # Update package version entry in uv.lock if matching current version
+                pattern = rf'(name\s*=\s*"{re.escape(project_root.name)}"\nversion\s*=\s*)"{re.escape(info.version)}"'
+                if re.search(pattern, lock_text):
+                    lock_updated = re.sub(pattern, f'\\1"{new_v}"', lock_text, count=1)
+                    uv_lock.write_text(lock_updated, encoding="utf-8")
+            except Exception:
+                pass
+
+    elif source == "package.json":
+        file_path = project_root / "package.json"
+        content = file_path.read_text(encoding="utf-8")
+        updated = re.sub(
+            r'("version"\s*:\s*)"(.*?)"', f'\\1"{new_v}"', content, count=1
+        )
+        file_path.write_text(updated, encoding="utf-8")
+
+    elif source == "Cargo.toml":
+        file_path = project_root / "Cargo.toml"
+        content = file_path.read_text(encoding="utf-8")
+        updated = re.sub(
+            r'^(version\s*=\s*)"(.*?)"',
+            f'\\1"{new_v}"',
+            content,
+            count=1,
+            flags=re.MULTILINE,
+        )
+        file_path.write_text(updated, encoding="utf-8")
+
+    elif source.endswith(".csproj"):
+        file_path = project_root / source
+        content = file_path.read_text(encoding="utf-8")
+        updated = re.sub(
+            r"(<Version>)(.*?)(</Version>)", f"\\1{new_v}\\3", content, count=1
+        )
+        file_path.write_text(updated, encoding="utf-8")
+
+    elif source == "pom.xml":
+        file_path = project_root / "pom.xml"
+        content = file_path.read_text(encoding="utf-8")
+        updated = re.sub(
+            r"(<version>)(.*?)(</version>)", f"\\1{new_v}\\3", content, count=1
+        )
+        file_path.write_text(updated, encoding="utf-8")
+
+    elif "gradle" in source:
+        file_path = project_root / source
+        content = file_path.read_text(encoding="utf-8")
+        updated = re.sub(
+            r'(version\s*=\s*["\'])(.*?)(["\'])', f"\\1{new_v}\\3", content, count=1
+        )
+        file_path.write_text(updated, encoding="utf-8")
+
+    else:
+        raise RuntimeError(
+            f"Cannot bump version: unsupported project file source {source!r}"
+        )
+
+    verify_info = get_project_version(project_root)
+    if verify_info.version != new_v:
+        raise RuntimeError(
+            f"Version bump failed: expected {new_v}, got {verify_info.version}"
+        )
+    return new_v
+
+
+def _commit_version_bump(
+    console: Optional[Console],
+    git_root: Path,
+    project_root: Path,
+    new_v: str,
+    *,
+    allow_amend: bool = True,
+) -> str:
+    staged = _stage_version_files(git_root, project_root)
+    if not staged:
+        raise RuntimeError("No version files found to stage after bump.")
+
+    diff_staged = _git("diff", "--cached", "--name-only", cwd=git_root)
+    if diff_staged.returncode == 0 and diff_staged.stdout.strip():
+        staged_all = set(diff_staged.stdout.strip().splitlines())
+        unrelated = staged_all - set(staged)
+        if unrelated:
+            raise RuntimeError(
+                "Refusing to commit version bump: unrelated files are staged: "
+                + ", ".join(sorted(unrelated))
+            )
+
+    amend = False
+    if allow_amend:
+        ok, reason = _can_amend_version_safely(git_root)
+        if ok:
+            amend = True
+            msg_res = _git("log", "-1", "--format=%B", cwd=git_root)
+            existing_msg = (
+                msg_res.stdout.strip()
+                if msg_res.returncode == 0
+                else "chore: bump version"
+            )
+            commit_res = _git("commit", "--amend", "-m", existing_msg, cwd=git_root)
+            if commit_res.returncode != 0:
+                err = (commit_res.stderr or commit_res.stdout or "").strip()
+                raise RuntimeError(f"Failed to amend version bump: {err}")
+            if console:
+                console.print(
+                    f"[dim]Amended version {new_v} into HEAD ({reason})[/dim]"
+                )
+
+    if not amend:
+        msg = f"chore(release): v{new_v}"
+        commit_res = _git("commit", "-m", msg, cwd=git_root)
+        if commit_res.returncode != 0:
+            err = (commit_res.stderr or commit_res.stdout or "").strip()
+            if "nothing to commit" in err.lower():
+                if console:
+                    console.print(
+                        f"[dim]Version bump for {new_v} produced no changes to commit.[/dim]"
+                    )
+            else:
+                raise RuntimeError(f"Failed to commit version bump: {err}")
+        else:
+            if console:
+                console.print(f"[bold green]Committed version bump: {msg}[/bold green]")
+
+    committed_info = inspect_committed(git_root)
+    if committed_info.version != new_v:
+        raise RuntimeError(
+            f"Post-commit verification failed: HEAD has version {committed_info.version!r}, "
+            f"expected {new_v!r}."
+        )
+
+    return "amend" if amend else "commit"
+
+
+def promote_version(
+    part: str,
+    *,
+    project_root: Optional[Path] = None,
+    console: Optional[Console] = None,
+    allow_amend: bool = True,
+) -> str:
+    """Bump project version and commit it. Returns the new version string."""
+    project_root = (project_root or Path.cwd()).resolve()
+    git_root = _find_git_root(project_root)
+    if not git_root:
+        raise RuntimeError("Not inside a git repository.")
+
+    working_info = get_project_version(project_root)
+    if not working_info.source or working_info.version == "unknown":
+        raise RuntimeError(
+            "Could not find a project version file (pyproject.toml / package.json)."
+        )
+
+    pre_committed_info = inspect_committed(git_root)
+    if console:
+        console.print(
+            f"[blue]Bumping {part} from working {working_info.version} "
+            f"(HEAD {pre_committed_info.version}) via {working_info.source}...[/blue]"
+        )
+
+    new_v = _bump_project_version(part, project_root, working_info.source)
+    if console:
+        console.print(f"[bold green]Promoted to version {new_v}[/bold green]")
+    _commit_version_bump(
+        console, git_root, project_root, new_v, allow_amend=allow_amend
+    )
+    return new_v

verkit-0.1.1/src/verkit/tagger.py

@@ -0,0 +1,162 @@
+import os
+import subprocess
+from pathlib import Path
+from typing import Optional, Tuple
+
+from rich.console import Console
+
+from verkit.inspector import get_project_version, inspect_committed
+
+
+def _git(*args: str, cwd: Optional[Path] = None) -> subprocess.CompletedProcess:
+    cmd = ["git"]
+    if cwd is not None:
+        cmd += ["-C", str(cwd)]
+    cmd.extend(args)
+    return subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=False,
+        shell=(os.name == "nt"),
+    )
+
+
+def _find_git_root(path: Path) -> Optional[Path]:
+    res = _git("rev-parse", "--show-toplevel", cwd=path)
+    if res.returncode == 0 and res.stdout.strip():
+        return Path(res.stdout.strip()).resolve()
+    return None
+
+
+def _git_head_sha(git_root: Path) -> Optional[str]:
+    res = _git("rev-parse", "HEAD", cwd=git_root)
+    if res.returncode == 0 and res.stdout.strip():
+        return res.stdout.strip()
+    return None
+
+
+def _git_tag_target(git_root: Path, tag_name: str) -> Optional[str]:
+    res = _git("rev-parse", f"refs/tags/{tag_name}^{{}}", cwd=git_root)
+    if res.returncode == 0 and res.stdout.strip():
+        return res.stdout.strip()
+    res2 = _git("rev-parse", f"refs/tags/{tag_name}", cwd=git_root)
+    if res2.returncode == 0 and res2.stdout.strip():
+        return res2.stdout.strip()
+    return None
+
+
+def _push_branch_and_tag(
+    console: Optional[Console],
+    git_root: Path,
+    tag_name: str,
+    *,
+    push_branch: bool = True,
+):
+    if push_branch:
+        branch_res = _git("rev-parse", "--abbrev-ref", "HEAD", cwd=git_root)
+        branch = branch_res.stdout.strip() if branch_res.returncode == 0 else ""
+        if not branch or branch == "HEAD":
+            raise RuntimeError("Cannot push branch from detached HEAD state.")
+        if console:
+            console.print(f"[blue]Pushing branch {branch} to origin...[/blue]")
+        res = _git("push", "origin", branch, cwd=git_root)
+        if res.returncode != 0:
+            err = (res.stderr or res.stdout or "").strip()
+            raise RuntimeError(f"Failed to push branch {branch}: {err}")
+        if console:
+            console.print(f"[bold green]Pushed branch {branch}[/bold green]")
+
+    if console:
+        console.print(f"[blue]Pushing tag {tag_name} to origin...[/blue]")
+    res = _git("push", "origin", tag_name, cwd=git_root)
+    if res.returncode != 0:
+        err = (res.stderr or res.stdout or "").strip()
+        raise RuntimeError(f"Failed to push tag {tag_name}: {err}")
+    if console:
+        console.print(f"[bold green]Pushed tag {tag_name}[/bold green]")
+
+
+def tag_version(
+    *,
+    project_root: Optional[Path] = None,
+    console: Optional[Console] = None,
+    push: bool = True,
+    push_branch: bool = True,
+) -> str:
+    """Create ``vX.Y.Z`` on HEAD from the *committed* version and optionally push."""
+    project_root = (project_root or Path.cwd()).resolve()
+    git_root = _find_git_root(project_root)
+    if not git_root:
+        raise RuntimeError("Not inside a git repository.")
+
+    committed_info = inspect_committed(git_root)
+    if committed_info.version == "unknown":
+        raise RuntimeError("Could not read version from HEAD. Promote first.")
+
+    working_info = get_project_version(project_root)
+    if working_info.version != "unknown" and working_info.version != committed_info.version:
+        raise RuntimeError(
+            f"Working tree version {working_info.version} differs from HEAD {committed_info.version}. "
+            "Commit or discard local version edits before tagging."
+        )
+
+    tag_name = f"v{committed_info.version}"
+    head = _git_head_sha(git_root)
+    if not head:
+        raise RuntimeError("Could not resolve HEAD.")
+
+    existing = _git_tag_target(git_root, tag_name)
+    if existing:
+        head_full = _git("rev-parse", head, cwd=git_root).stdout.strip() or head
+        existing_full = (
+            _git("rev-parse", existing, cwd=git_root).stdout.strip() or existing
+        )
+        if existing_full == head_full:
+            if console:
+                console.print(f"[dim]Tag {tag_name} already points at HEAD[/dim]")
+        else:
+            raise RuntimeError(
+                f"Tag {tag_name} already exists but points at {existing_full[:12]}, "
+                f"not HEAD ({head_full[:12]})."
+            )
+    else:
+        res = _git("tag", tag_name, cwd=git_root)
+        if res.returncode != 0:
+            err = (res.stderr or res.stdout or "").strip()
+            raise RuntimeError(f"Failed to create tag {tag_name}: {err}")
+        if console:
+            console.print(
+                f"[bold green]Tagged HEAD as {tag_name}[/bold green] "
+                f"[dim]({head[:12]})[/dim]"
+            )
+
+    if push:
+        _push_branch_and_tag(console, git_root, tag_name, push_branch=push_branch)
+    elif console:
+        console.print(
+            f"[dim]Skipped push. When ready: git push && git push origin {tag_name}[/dim]"
+        )
+
+    return tag_name
+
+
+def release_version(
+    part: str,
+    *,
+    project_root: Optional[Path] = None,
+    console: Optional[Console] = None,
+    push: bool = True,
+    push_branch: bool = True,
+) -> Tuple[str, str]:
+    """Atomic promote + tag + push release workflow."""
+    from verkit.promoter import promote_version
+
+    new_v = promote_version(part, project_root=project_root, console=console)
+    tag_name = tag_version(
+        project_root=project_root,
+        console=console,
+        push=push,
+        push_branch=push_branch,
+    )
+    return new_v, tag_name

verkit-0.1.1/tests/test_inspector.py

@@ -0,0 +1,20 @@
+from verkit.inspector import inspect_project
+
+def test_inspect_python_project(tmp_path):
+    pyproject = tmp_path / "pyproject.toml"
+    pyproject.write_text('[project]\nname = "myproject"\nversion = "1.2.3"\n')
+    info = inspect_project(tmp_path)
+    assert info.version == "1.2.3"
+    assert info.source == "pyproject.toml"
+
+def test_inspect_node_project(tmp_path):
+    pkg = tmp_path / "package.json"
+    pkg.write_text('{"name": "my-node-app", "version": "2.0.0"}')
+    info = inspect_project(tmp_path)
+    assert info.version == "2.0.0"
+    assert info.source == "package.json"
+
+def test_inspect_unknown_project(tmp_path):
+    info = inspect_project(tmp_path)
+    assert info.version == "unknown"
+    assert info.source is None

verkit-0.1.1/tests/test_promoter.py

@@ -0,0 +1,7 @@
+from verkit.promoter import _increment_semver
+
+def test_increment_semver():
+    assert _increment_semver("0.1.0", "patch") == "0.1.1"
+    assert _increment_semver("0.1.0", "minor") == "0.2.0"
+    assert _increment_semver("0.1.0", "major") == "1.0.0"
+    assert _increment_semver("1.2.3-rc1", "patch") == "1.2.4-rc1"

verkit-0.1.1/uv.lock

@@ -0,0 +1,80 @@
+version = 1
+revision = 3
+requires-python = ">=3.9"
+resolution-markers = [
+    "python_full_version >= '3.10'",
+    "python_full_version < '3.10'",
+]
+
+[[package]]
+name = "markdown-it-py"
+version = "3.0.0"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version < '3.10'",
+]
+dependencies = [
+    { name = "mdurl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/38/71/3b932df36c1a044d397a1f92d1cf91ee0a503d91e470cbd670aa66b07ed0/markdown-it-py-3.0.0.tar.gz", hash = "sha256:e3f60a94fa066dc52ec76661e37c851cb232d92f9886b15cb560aaada2df8feb", size = 74596, upload-time = "2023-06-03T06:41:14.443Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/42/d7/1ec15b46af6af88f19b8e5ffea08fa375d433c998b8a7639e76935c14f1f/markdown_it_py-3.0.0-py3-none-any.whl", hash = "sha256:355216845c60bd96232cd8d8c40e8f9765cc86f46880e43a8fd22dc1a1a8cab1", size = 87528, upload-time = "2023-06-03T06:41:11.019Z" },
+]
+
+[[package]]
+name = "markdown-it-py"
+version = "4.2.0"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version >= '3.10'",
+]
+dependencies = [
+    { name = "mdurl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/ff/7841249c247aa650a76b9ee4bbaeae59370dc8bfd2f6c01f3630c35eb134/markdown_it_py-4.2.0.tar.gz", hash = "sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49", size = 82454, upload-time = "2026-05-07T12:08:28.36Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" },
+]
+
+[[package]]
+name = "mdurl"
+version = "0.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.20.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
+]
+
+[[package]]
+name = "rich"
+version = "15.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown-it-py", version = "3.0.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },
+    { name = "markdown-it-py", version = "4.2.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.10'" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c0/8f/0722ca900cc807c13a6a0c696dacf35430f72e0ec571c4275d2371fca3e9/rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36", size = 230680, upload-time = "2026-04-12T08:24:00.75Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" },
+]
+
+[[package]]
+name = "verkit"
+version = "0.1.1"
+source = { editable = "." }
+dependencies = [
+    { name = "rich" },
+]
+
+[package.metadata]
+requires-dist = [{ name = "rich", specifier = ">=10.0.0" }]