kvseo 0.6.6__tar.gz

kvseo-0.6.6/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [dev, main]
+  pull_request:
+    branches: [dev, main]
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint (ruff)
+        run: ruff check .
+      - name: Type-check (mypy)
+        run: mypy
+      - name: Test (pytest)
+        run: pytest -q

kvseo-0.6.6/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+# Tag-triggered PyPI publish via OIDC trusted publishing — no tokens at rest.
+# Flow: /bump → sync main → `git tag vX.Y.Z` → `git push origin vX.Y.Z`.
+# One-time setup (kVadrum, on PyPI): configure a Trusted Publisher / pending
+# publisher for project `kvseo`, owner `kVadrum`, repo `kvseo`, workflow
+# `release.yml`, environment `pypi`. See STATE.md "Publishing".
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write  # OIDC: lets PyPI mint a short-lived publish credential
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify tag matches package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")"
+          echo "tag=$tag pyproject=$pkg"
+          [ "$tag" = "$pkg" ] || { echo "::error::tag v$tag does not match pyproject version $pkg"; exit 1; }
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check artifacts render on PyPI
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

kvseo-0.6.6/.gitignore

@@ -0,0 +1,42 @@
+# --- Local-only dev files (never committed — workspace policy) ---
+CLAUDE.md
+STATE.md
+.claude/
+
+# --- Internal spec & design docs (never committed — workspace policy) ---
+# Numbered handoff/spec series (00-handoff.md … 10-risks…) + decision records.
+[0-9][0-9]-*.md
+adrs/
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.python-version
+
+# --- Tooling caches ---
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# --- Local data / secrets ---
+.env
+*.db
+*.sqlite
+*.sqlite3
+*.sqlite3-wal
+*.sqlite3-shm
+
+# --- OS cruft ---
+.DS_Store
+Thumbs.db

kvseo-0.6.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KeMeK Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kvseo-0.6.6/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: kvseo
+Version: 0.6.6
+Summary: An AI-native SEO copilot for solo operators and small agencies — the AI layer over your existing SEO stack.
+Project-URL: Homepage, https://github.com/kvadrum/kvseo
+Project-URL: Repository, https://github.com/kvadrum/kvseo
+Author: kVadrum
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,audit,cli,core-web-vitals,llm,search-console,seo
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Requires-Python: >=3.12
+Requires-Dist: alembic>=1.13
+Requires-Dist: google-auth-oauthlib>=1.2
+Requires-Dist: google-auth>=2.29
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: keyring>=25
+Requires-Dist: litellm<2,>=1.40
+Requires-Dist: markdown>=3.6
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: selectolax>=0.3.21
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-markdown; extra == 'dev'
+Provides-Extra: pdf
+Requires-Dist: playwright>=1.44; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# kvseo
+
+**The AI layer over your existing SEO stack.**
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![Built in public](https://img.shields.io/badge/built%20in%20public-kVadrum-e2725b.svg)](https://kvadrum.com)
+
+`kvseo` is an AI-native SEO copilot for solo operators and small agencies. It
+doesn't replace your data tools — it sits on top of them. Point it at a URL and
+it runs an on-page audit, folds in Core Web Vitals and Search Console context,
+and produces a prioritized, *reasoned* action list plus a client-ready report.
+
+The data layer is a commodity. What `kvseo` adds is the layer the others skip:
+**synthesis, AI-assisted prioritization, and agency-shaped reporting** — as a
+fast, local, single-command CLI.
+
+> **Status: v0.1 feature-complete.** The full pipeline (audit → advise → report)
+> runs end-to-end and is code-reviewed, type-checked, and tested throughout. Not
+> yet on PyPI — install from source today (see [Install](#install)); the tagged
+> release is imminent.
+
+---
+
+## Quickstart
+
+Once installed (see [Install](#install)):
+
+```console
+$ kvseo init                        # create config + a local SQLite database
+$ kvseo audit https://example.com   # on-page audit + Core Web Vitals → HTML report
+```
+
+That loop needs **no API keys and no accounts**. `audit` writes a self-contained
+HTML report to the current directory and prints the findings to your terminal.
+Add data sources and an LLM to go deeper:
+
+```console
+$ kvseo connect psi --api-key <key>                          # PageSpeed Insights (free; raises CWV limits)
+$ kvseo connect csv export.csv --site https://example.com/   # import a GSC CSV export — no OAuth
+$ kvseo connect gsc                                          # …or connect Search Console via OAuth
+$ export ANTHROPIC_API_KEY=…                                 # bring your own LLM key (any LiteLLM provider)
+$ kvseo audit https://example.com                            # now with GSC context + an AI action list
+$ kvseo cost                                                 # what the advisor spent, by provider / model
+```
+
+## What it does
+
+- **On-page audit** — 19 checks across title, meta, headings, content, schema,
+  images, and internal links, rolled into a single 0–100 score.
+- **Core Web Vitals** — CrUX field data + Lighthouse lab metrics via the free
+  PageSpeed Insights API (works keyless at lower rate limits).
+- **Search Console context** — real query / click / impression / position data
+  per URL, via OAuth **or** a plain CSV export (the no-API escape hatch).
+- **AI advisor** — a prioritized "what to do next" list where every
+  recommendation is traceable to a specific finding. **Bring your own LLM key**
+  (Anthropic, OpenAI, Gemini, or a local Ollama — anything LiteLLM speaks to).
+  kvseo never proxies your key or marks up tokens, and `kvseo cost` shows exactly
+  what each run spent.
+- **Reports** — a self-contained, single-file HTML report (inline CSS, embedded
+  data, zero external requests, print-to-PDF friendly) plus clean Markdown.
+  PDF/DOCX land in v0.2.
+
+Everything **degrades gracefully**: the audit and HTML report work with no LLM
+key at all — the advisor is an optional layer you unlock by adding a provider
+key. No PSI key → the Core Web Vitals checks skip; no Search Console → the audit
+still scores the page.
+
+## Principles
+
+- **BYO-key.** kvseo never ships, proxies, or marks up an LLM key.
+- **Local-first.** Everything lives in one SQLite file on your machine — no
+  account, no cloud.
+- **Read-only.** kvseo pulls from APIs you authorize; it never writes upstream.
+- **No telemetry.** No phone-home, no usage metrics — not unless you opt in.
+- **Reproducible.** Every audit and advisor run is stored and re-runnable; the
+  advisor works from stored data, so you can re-prioritize without re-fetching.
+
+## Install
+
+Requires **Python 3.12+**.
+
+```console
+# from PyPI (once published):
+pipx install kvseo
+
+# from source (works today):
+git clone https://github.com/kVadrum/kvseo && cd kvseo
+python3.12 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+kvseo --version
+```
+
+Config lives in `~/.config/kvseo/` and data in `~/.local/share/kvseo/` (XDG;
+`%APPDATA%` / `%LOCALAPPDATA%` on Windows). Override either with the
+`KVSEO_CONFIG_DIR` / `KVSEO_DATA_DIR` environment variables.
+
+## License
+
+[MIT](./LICENSE) — free to use, modify, and distribute. KeMeK Network © 2026.
+
+### Trademarks
+
+The "kvseo" and "kVadrum" names are trademarks of KeMeK Network. They are not
+covered by the MIT license, and no rights to use the names are granted by this
+repository. Independent forks must replace the brand name with their own.
+
+A [kVadrum](https://kvadrum.com) Lab project, built in public.

kvseo-0.6.6/README.md

@@ -0,0 +1,108 @@
+# kvseo
+
+**The AI layer over your existing SEO stack.**
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![Built in public](https://img.shields.io/badge/built%20in%20public-kVadrum-e2725b.svg)](https://kvadrum.com)
+
+`kvseo` is an AI-native SEO copilot for solo operators and small agencies. It
+doesn't replace your data tools — it sits on top of them. Point it at a URL and
+it runs an on-page audit, folds in Core Web Vitals and Search Console context,
+and produces a prioritized, *reasoned* action list plus a client-ready report.
+
+The data layer is a commodity. What `kvseo` adds is the layer the others skip:
+**synthesis, AI-assisted prioritization, and agency-shaped reporting** — as a
+fast, local, single-command CLI.
+
+> **Status: v0.1 feature-complete.** The full pipeline (audit → advise → report)
+> runs end-to-end and is code-reviewed, type-checked, and tested throughout. Not
+> yet on PyPI — install from source today (see [Install](#install)); the tagged
+> release is imminent.
+
+---
+
+## Quickstart
+
+Once installed (see [Install](#install)):
+
+```console
+$ kvseo init                        # create config + a local SQLite database
+$ kvseo audit https://example.com   # on-page audit + Core Web Vitals → HTML report
+```
+
+That loop needs **no API keys and no accounts**. `audit` writes a self-contained
+HTML report to the current directory and prints the findings to your terminal.
+Add data sources and an LLM to go deeper:
+
+```console
+$ kvseo connect psi --api-key <key>                          # PageSpeed Insights (free; raises CWV limits)
+$ kvseo connect csv export.csv --site https://example.com/   # import a GSC CSV export — no OAuth
+$ kvseo connect gsc                                          # …or connect Search Console via OAuth
+$ export ANTHROPIC_API_KEY=…                                 # bring your own LLM key (any LiteLLM provider)
+$ kvseo audit https://example.com                            # now with GSC context + an AI action list
+$ kvseo cost                                                 # what the advisor spent, by provider / model
+```
+
+## What it does
+
+- **On-page audit** — 19 checks across title, meta, headings, content, schema,
+  images, and internal links, rolled into a single 0–100 score.
+- **Core Web Vitals** — CrUX field data + Lighthouse lab metrics via the free
+  PageSpeed Insights API (works keyless at lower rate limits).
+- **Search Console context** — real query / click / impression / position data
+  per URL, via OAuth **or** a plain CSV export (the no-API escape hatch).
+- **AI advisor** — a prioritized "what to do next" list where every
+  recommendation is traceable to a specific finding. **Bring your own LLM key**
+  (Anthropic, OpenAI, Gemini, or a local Ollama — anything LiteLLM speaks to).
+  kvseo never proxies your key or marks up tokens, and `kvseo cost` shows exactly
+  what each run spent.
+- **Reports** — a self-contained, single-file HTML report (inline CSS, embedded
+  data, zero external requests, print-to-PDF friendly) plus clean Markdown.
+  PDF/DOCX land in v0.2.
+
+Everything **degrades gracefully**: the audit and HTML report work with no LLM
+key at all — the advisor is an optional layer you unlock by adding a provider
+key. No PSI key → the Core Web Vitals checks skip; no Search Console → the audit
+still scores the page.
+
+## Principles
+
+- **BYO-key.** kvseo never ships, proxies, or marks up an LLM key.
+- **Local-first.** Everything lives in one SQLite file on your machine — no
+  account, no cloud.
+- **Read-only.** kvseo pulls from APIs you authorize; it never writes upstream.
+- **No telemetry.** No phone-home, no usage metrics — not unless you opt in.
+- **Reproducible.** Every audit and advisor run is stored and re-runnable; the
+  advisor works from stored data, so you can re-prioritize without re-fetching.
+
+## Install
+
+Requires **Python 3.12+**.
+
+```console
+# from PyPI (once published):
+pipx install kvseo
+
+# from source (works today):
+git clone https://github.com/kVadrum/kvseo && cd kvseo
+python3.12 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+kvseo --version
+```
+
+Config lives in `~/.config/kvseo/` and data in `~/.local/share/kvseo/` (XDG;
+`%APPDATA%` / `%LOCALAPPDATA%` on Windows). Override either with the
+`KVSEO_CONFIG_DIR` / `KVSEO_DATA_DIR` environment variables.
+
+## License
+
+[MIT](./LICENSE) — free to use, modify, and distribute. KeMeK Network © 2026.
+
+### Trademarks
+
+The "kvseo" and "kVadrum" names are trademarks of KeMeK Network. They are not
+covered by the MIT license, and no rights to use the names are granted by this
+repository. Independent forks must replace the brand name with their own.
+
+A [kVadrum](https://kvadrum.com) Lab project, built in public.

kvseo-0.6.6/alembic.ini

@@ -0,0 +1,44 @@
+# Alembic config for in-repo development (dev `alembic` CLI invocations).
+# Runtime migrations are driven programmatically via kvseo.storage.db.migrate,
+# which builds its own Config — this file is for `alembic revision` /
+# `alembic upgrade` / `alembic check` from the repo root.
+
+[alembic]
+script_location = src/kvseo/storage/migrations
+file_template = %%(rev)s_%%(slug)s
+prepend_sys_path = src
+sqlalchemy.url = sqlite:///./kvseo-dev.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

kvseo-0.6.6/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kvseo"
+description = "An AI-native SEO copilot for solo operators and small agencies — the AI layer over your existing SEO stack."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "kVadrum" }]
+keywords = ["seo", "audit", "llm", "ai", "cli", "search-console", "core-web-vitals"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Site Management",
+]
+# Canonical version literal — /bump and bump-audit.sh target this field.
+version = "0.6.6"
+
+# Runtime dependencies. The advisor (LiteLLM) is core IP per ADR-002; storage
+# is SQLAlchemy + Alembic per ADR-003. Bounds are deliberately loose for the
+# scaffold; LiteLLM gets a minor-pin once a snapshot baseline exists (ADR-002,
+# risk R7).
+dependencies = [
+    "typer>=0.12",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.3",
+    "sqlalchemy>=2.0",
+    "alembic>=1.13",
+    "litellm>=1.40,<2",
+    "jinja2>=3.1",
+    "markdown>=3.6",
+    "selectolax>=0.3.21",
+    "platformdirs>=4.2",
+    "keyring>=25",
+    "google-auth>=2.29",
+    "google-auth-oauthlib>=1.2",
+]
+
+[project.optional-dependencies]
+# PDF rendering lands in v0.2 (ADR-005); declared here so the extra name is
+# stable from day one. Not installed by default.
+pdf = ["playwright>=1.44"]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "types-Markdown",
+]
+
+[project.scripts]
+kvseo = "kvseo.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/kvadrum/kvseo"
+Repository = "https://github.com/kvadrum/kvseo"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kvseo"]
+
+[tool.ruff]
+line-length = 120  # settled width — fits a typed mapped_column or a message-bearing check return on one line
+target-version = "py312"
+src = ["src", "tests"]
+# Alembic migration scripts are generated and follow Alembic's own style.
+extend-exclude = ["src/kvseo/storage/migrations"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4", "PTH", "RUF"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src/kvseo"]
+# Alembic env/versions use dynamic context objects; not worth strict-typing.
+exclude = ["^src/kvseo/storage/migrations/"]
+# These ship partial or no type stubs; don't fail strict on them.
+[[tool.mypy.overrides]]
+module = ["selectolax.*", "litellm.*", "google.*", "google_auth_oauthlib.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

kvseo-0.6.6/src/kvseo/__init__.py

@@ -0,0 +1,18 @@
+"""kvseo — an AI-native SEO copilot for solo operators and small agencies.
+
+The canonical version is the ``version`` field in ``pyproject.toml`` (what
+/bump and bump-audit edit). ``__version__`` resolves it from installed package
+metadata at runtime; the literal below is only a fallback for running against
+an uninstalled source tree.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("kvseo")
+except PackageNotFoundError:  # not installed (e.g. running from a source tree)
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

kvseo-0.6.6/src/kvseo/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m kvseo`` as an alias for the ``kvseo`` console script."""
+
+from __future__ import annotations
+
+from kvseo.cli import app
+
+if __name__ == "__main__":
+    app()

kvseo-0.6.6/src/kvseo/cli/__init__.py

@@ -0,0 +1,56 @@
+"""kvseo command-line interface (Typer).
+
+This module is the only entry point in v0.1. It is a thin shell over
+``kvseo.core``; all business logic lives below the CLI (see 02-architecture.md
+§2 for the layering rule).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kvseo import __version__
+from kvseo.cli import advisor, audit, config, connect, cost, init, report
+
+app = typer.Typer(
+    name="kvseo",
+    help="AI-native SEO copilot for solo operators and small agencies.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kvseo {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show the kvseo version and exit.",
+            is_eager=True,
+            callback=_version_callback,
+        ),
+    ] = False,
+) -> None:
+    """kvseo — the AI layer over your existing SEO stack."""
+
+
+# --- Command wiring -------------------------------------------------------
+# Top-level verbs.
+app.command()(init.init)
+app.command()(audit.audit)
+app.command()(report.report)
+app.command()(cost.cost)
+# Sub-command groups.
+app.add_typer(connect.app, name="connect")
+app.add_typer(config.app, name="config")
+app.add_typer(advisor.app, name="advisor")

kvseo-0.6.6/src/kvseo/cli/_util.py

@@ -0,0 +1,27 @@
+"""Shared CLI helpers used across kvseo command modules.
+
+Small building blocks the command modules reach for — an error-exit helper and
+the audit-ID parser — kept here so their message + exit-code contract has one
+home instead of a copy per command.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import NoReturn
+
+import typer
+
+
+def fail(message: str, *, code: int) -> NoReturn:
+    """Print an error line to stderr (red) and exit with ``code``."""
+    typer.secho(message, fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=code)
+
+
+def parse_audit_id(value: str) -> uuid.UUID:
+    """Parse a CLI-supplied audit ID, or exit 2 with a clear message."""
+    try:
+        return uuid.UUID(value)
+    except ValueError:
+        fail(f"'{value}' is not a valid audit ID.", code=2)