Metadata-Version: 2.5
Name: rb-keys
Version: 0.2.5
Summary: Shared normalization keys (query, domain, URL) for linking records across tools.
Project-URL: Repository, https://github.com/bolandeu/keys
Author: Roman Bolandau
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.14
Requires-Dist: packaging>=24.0
Requires-Dist: platformdirs>=4.2
Requires-Dist: pydantic>=2.6
Requires-Dist: rich>=13.7
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer<0.29,>=0.27
Requires-Dist: w3lib>=2.5.0
Description-Content-Type: text/markdown

# rb-keys

Shared normalization keys (query, domain, URL) for linking records across tools

## Usage

```python
from rb_keys import KEYS_VERSION, norm_domain, norm_query, norm_url

norm_query("!Купить  Ёлку -бесплатно")  # "купить елку"
norm_domain("https://WWW.xn--e1afmkfd.xn--p1ai:443/")  # "пример.рф"
norm_url("https://www.example.com/Catalog/?utm_source=x&p=2#top")  # "example.com/Catalog?p=2"
```

Not in Python: `keys query|domain|url VALUE [--json]` prints the key (`--json`:
`{"ok": true, "fn", "input", "key", "keys_version"}`; not a URL → exit 2 `INVALID_ARGUMENTS`).
Batch: `keys query|domain|url A B … [--input FILE|-] [--json]` — one process for many values;
`--json`: `{"ok": true, "fn", "count", "keys_version", "results": [{"input", "key"}]}` in input order.
The rules are the contract vectors in [`vectors/keys-v1.yaml`](vectors/keys-v1.yaml) —
run them against your own implementation as a contract test.

## Development

```bash
uv sync
uv run keys --help
uv run pytest --snapshot-update  # after changing a command's help; review tests/snapshots/help/
```

The gate is `gate check`, run on this machine before a commit.
`pytest` fails below the coverage floor in `pyproject.toml`; `ruff` includes the security (`S`) rules.

## Release

The version is the git tag (`vX.Y.Z`) — `pyproject.toml` has no `version =`. Releases are the gate, the tag (`vX.Y.Z`), `uv build` and the GitHub release with the built artifacts.

## Install

```bash
```

From the git tag instead (never a branch):

```bash
uv tool install "rb-keys @ git+https://homeserver.tailee01ab.ts.net:3000/bolandeu/keys.git@vX.Y.Z"
```

Replace `vX.Y.Z` with the latest release tag. An AI agent bootstraps the CLI the same way — see
`src/rb_keys/data/SKILL.md`. Update an installed copy: `uv tool upgrade rb-keys`.

After install, the command `keys` is available globally, on macOS, Linux and Windows alike.

## Architecture

This project follows a fixed CLI architecture:

- `src/rb_keys/commands/` — argument parsing only, no business logic.
- `src/rb_keys/core/` — services, models, errors: the real logic.
- `src/rb_keys/providers/` — external APIs/integrations.
- `src/rb_keys/credentials/` — secrets via the OS keychain (`keyring`)
  and environment variables. Secrets never live in `.rb_keys/config.toml`.
- `src/rb_keys/output/` — human (`rich`) and `--json` rendering.

Run `keys doctor` to check environment/config/auth readiness, and
`keys --help` for the full command surface. Every command supports
`--json` for machine/agent consumption; errors are structured (`error.code`,
fixed exit codes, `error.action` telling you what to do next) and go to
stderr in human mode, so stdout is always safe to pipe.

A project can require a minimum CLI version in its `.rb_keys/config.toml`
(`[cli] min_version = "..."`); an older install refuses with exit 6 and
`uv tool upgrade rb-keys` fixes it.

See `src/rb_keys/data/SKILL.md` for the agent-facing usage guide
bundled with this package — install it into an AI tool with
`keys skill install`, or get it as plain text with
`keys --ai` (works even without file access).
