krkn-docs-bot

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 24 Open GitHub ↗

Documentation sync bot for krkn-chaos ecosystem

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# krkn-docs-bot

[![CI](https://github.com/StrikerEureka34/krkn-docs-bot/actions/workflows/ci.yml/badge.svg)](https://github.com/StrikerEureka34/krkn-docs-bot/actions/workflows/ci.yml)

Automated documentation sync bot for [krkn-chaos](https://krkn-chaos.dev). Detects when a merged PR in [krkn-hub](https://github.com/krkn-chaos/krkn-hub) changes scenario parameters, generates updated Hugo tab files, and opens a draft PR on the website repository for human review.

## How it works

![How it works](https://raw.githubusercontent.com/StrikerEureka34/krkn-docs-bot/main/docs/how-it-works.jpeg)

Weekly drift scanner (`drift-report.yml`, also in the website repo) compares every `env.sh` against its published tab file and opens or updates a GitHub issue listing stale parameters.

## Repository layout

```
bot/
  doc_bot.py         - entry point: event-driven and targeted /fix mode
  drift_scanner.py   - weekly drift scanner, posts GitHub issues
  parser.py          - env.sh and krknctl-input.json parsers
  renderer.py        - Hugo markdown tab file renderer
  gemini_client.py   - LLM client (OpenRouter / Nemotron-3-nano-30b)
  github_client.py   - GitHub API helpers (drift issue create/update)

tests/               - pytest suite (50+ tests, no network calls)
.github/workflows/
  ci.yml             - run tests on every push/PR
  doc-sync-receiver.yml  - development copy (uses DOCS_BOT_TOKEN PAT)
  drift-report.yml       - development copy
```

The **production** workflows live in the website repo (`StrikerEureka34/website_2`) and use a GitHub App token (`APP_ID` + `APP_PRIVATE_KEY`) so PRs show as authored by `krkn-docs-bot[bot]`.

## Quick start

```bash
pip install -r requirements.txt
export OPENROUTER_API_KEY=sk-...
export KRKN_HUB_PATH=/path/to/krkn-hub
export WEBSITE_ROOT=/path/to/website

# Generate tab files for one scenario
python -m bot.doc_bot --scenario node-interface-down

# Run drift scanner (prints report, no GitHub API call)
python -m bot.drift_scanner \
  --krkn-hub /path/to/krkn-hub \
  --website /path/to/website
```

## Running tests

```bash
pip install -r requirements.txt
pytest --tb=short -q
```

No API keys required -- all LLM calls are mocked in tests.

## AUTO marker system

Generated tab files contain fenced regions:

On subsequent runs the bot replaces only the content between these markers, preserving any human-written prose above or below the table. If an existing file lacks these markers (e.g. hand-written before the bot existed), the bot injects them around the existing parameter table rather than overwriting the file.

## Secrets required

| Secret | Used by | Purpose |
|--------|---------|---------|
| `OPENROUTER_API_KEY` | website / krkn-docs-bot | LLM calls via OpenRouter |
| `DOCS_BOT_TOKEN` | krkn-docs-bot dev workflows | PAT for checkout + PR creation |
| `APP_ID` | website production workflows | GitHub App ID |
| `APP_PRIVATE_KEY` | website production workflows | GitHub App private key |

## Related repos

- [krkn-chaos/website](https://github.com/krkn-chaos/website) - documentation site (Hugo/Docsy)
- [krkn-chaos/krkn-hub](https://github.com/krkn-chaos/krkn-hub) - upstream scenario source of truth
- Upstream issue: [krkn-chaos/website#320](https://github.com/krkn-chaos/website/issues/320)

krkn-docs-bot

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README