Metadata-Version: 2.4
Name: openclaw-route-check
Version: 0.1.1
Summary: Static routing checks for OpenClaw messages, cron jobs, and announce deliveries.
Project-URL: Homepage, https://github.com/pfrederiksen/openclaw-route-check
Project-URL: Repository, https://github.com/pfrederiksen/openclaw-route-check
Project-URL: Issues, https://github.com/pfrederiksen/openclaw-route-check/issues
Author: Peter Frederiksen
License-Expression: MIT
License-File: LICENSE
Keywords: ci,cli,openclaw,routing,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# openclaw-route-check

`openclaw-route-check` is a small static-analysis CLI for checking where OpenClaw messages, cron jobs, and announce deliveries are expected to route before you rely on them in production.

It focuses only on delivery and routing correctness. It does not send test messages.

## Install

```bash
pipx install openclaw-route-check
```

For local development:

```bash
uv sync
uv run openclaw-route-check --help
uv run pytest
```

## Examples

```bash
openclaw-route-check --job 429c62e0-2b1f-4179-bac3-792f405d09ae
openclaw-route-check --session agent:main:telegram:group:-1003710118964
openclaw-route-check --all-crons --markdown
openclaw-route-check --announce fixtures/announce.json --json
openclaw-route-check --channel telegram --target -1003710118964 --thread 77
```

By default, `--job` and `--all-crons` read `./jobs.json`. Use `--jobs path/to/jobs.json` to point at another file.

## What Is Checked

The checker resolves and reports:

- resolved channel
- resolved target or chat
- resolved thread or topic when present
- session target behavior
- routing confidence score
- warnings or errors that are suitable for CI

It detects:

- missing announce target
- mismatched `sessionKey` and delivery target
- likely thread/topic loss
- cron jobs relying on implicit routing where explicit routing would be safer
- ambiguous `channel: last` and `target: last` usage

## Supported Inputs

The analyzer intentionally accepts flexible JSON shapes because OpenClaw routing config can appear under different keys. It looks for route fields directly on an object and inside route-like containers such as `delivery`, `announce`, `route`, `routing`, `target`, and `destination`.

Recognized channel-like keys include:

```text
channel, transport, provider, driver, via
```

Recognized target-like keys include:

```text
target, chat, chat_id, chatId, room, room_id, to, recipient, target_id, targetId, channel_id, channelId
```

Recognized thread/topic keys include:

```text
thread, thread_id, threadId, topic, topic_id, topicId, message_thread_id, messageThreadId, forum_topic_id, forumTopicId
```

Session keys are parsed heuristically. A key like this:

```text
agent:main:telegram:group:-1003710118964:topic:77
```

resolves to:

- channel: `telegram`
- target/chat: `-1003710118964`
- thread/topic: `77`

## Output Formats

Terminal output is optimized for local inspection:

```bash
openclaw-route-check --job implicit-nightly --jobs fixtures/jobs.json
```

JSON output is suitable for CI automation:

```bash
openclaw-route-check --all-crons --jobs fixtures/jobs.json --json
```

Markdown output works well in GitHub Actions step summaries:

```bash
openclaw-route-check --all-crons --jobs fixtures/jobs.json --markdown >> "$GITHUB_STEP_SUMMARY"
```

Use `--strict` to return a non-zero exit code on warnings as well as errors.

## What Cannot Be Proven Statically

Static analysis cannot prove:

- whether an OpenClaw runtime session still exists
- whether `last` points at the conversation you expect
- whether credentials, bot membership, or permissions allow delivery
- whether Telegram forum topics or similar thread ids are still valid
- whether runtime code mutates routing after config load
- whether an external provider silently remaps channels, chats, or topics

The tool is best used as a preflight check for config shape and obvious routing risks before a production deploy.

## Development

```bash
uv sync
uv run pytest
uv run openclaw-route-check --all-crons --jobs fixtures/jobs.json
```

## Releases

This repository includes a tag-driven GitHub Actions release workflow. Tags matching `v*.*.*` build and publish the Python package to PyPI, then update `pfrederiksen/homebrew-tap`.

Recommended release flow:

```bash
git tag v0.1.1
git push origin v0.1.1
```

PyPI publishing is configured for trusted publishing via GitHub Actions. Do not commit PyPI tokens. Configure the PyPI project to trust this repository and workflow environment.

The Homebrew tap update requires a GitHub secret named `HOMEBREW_TAP_TOKEN` with permission to push to `pfrederiksen/homebrew-tap`.
