# devx — Reusable Development & CI/CD Tools

A Python package providing reusable development and CI/CD automation tools for oblachno-oss projects. devx consolidates release management, PR automation, wiki sync, badge generation, translation checks, and more into a single installable package.

> An open-source project from **Oblachno** (облачно means *cloudy* in Bulgarian).

[![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/LICENSE)
[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/badges/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/badges/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/badges/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/badges/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/badges/python.svg)](https://www.python.org/downloads/)

## Installation

Install from the Gitea PyPI registry:

```bash
pip install devx --index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
```

Or add the registry to your `pip.conf` / `pyproject.toml` and install normally:

```bash
pip install devx
```

## Usage

### CI/CD Automation

devx provides CI/CD modules invoked via `python -m devx.ci.*`:

```bash
# Release automation (versioning, changelog, tagging)
python -m devx.ci.release
python -m devx.ci.release --dry-run

# Publish a release to the Gitea PyPI registry
python -m devx.ci.publish v1.0.0 oblachno-oss/devx

# Automated PR review
python -m devx.ci.pr_review 42 oblachno-oss/devx

# Auto-merge a PR (validates title, squash-merges)
python -m devx.ci.auto_merge feature-branch "DEVX-12: Add feature" oblachno-oss/devx 42

# Classify changes (user-facing vs workflow-only)
python -m devx.ci.classify_changes --base origin/master --head HEAD --github-output

# Sync documentation to Gitea wiki
python -m devx.ci.sync_wiki --repo oblachno-oss/devx --strict

# Generate and push quality badges
python -m devx.ci.push_badges

# Check translation completeness
python -m devx.ci.check_translations

# Documentation coverage check
python -m devx.ci.doc_coverage --fail-on-missing

# Validate a commit message
python -m devx.ci.validate_commit_msg commit-msg.txt --branch master

# Notify on CI failure (creates a Gitea issue)
python -m devx.ci.notify_failure --repo oblachno-oss/devx --run-id 123 --workflow ci --commit abc123
```

### Developer Tools

devx provides developer tooling invoked via `python -m devx.tools.*`:

```bash
# Set up a development environment (venv, deps, hooks)
python -m devx.tools.setup --bin .venv/bin

# Install CI tools (actionlint, git-cliff, act_runner, tea)
python -m devx.tools.install_tools
python -m devx.tools.install_tools --tool git-cliff --tool tea

# Check unit test speed
python -m devx.tools.check_test_speed --max-seconds 10

# Configure repository (branch protection, labels)
python -m devx.tools.configure_repo
```

### CLI

devx also provides a `devx` CLI command:

```bash
devx --help
devx --version
```

### Configuration

devx reads configuration from environment variables with `.env` file fallback:

| Variable | Default | Description |
|----------|---------|-------------|
| `DEVX_GITEA_API_URL` | `https://git.oblachno.oblachno.fyi/api/v1` | Gitea API base URL |
| `DEVX_VIKUNJA_API_URL` | `https://work.oblachno.oblachno.fyi/api/v1` | Vikunja API base URL |
| `DEVX_LANG` | `en` | Language (en, bg) |
| `REPO_TOKEN` | — | Gitea API token |
| `VIKUNJA_TOKEN` | — | Vikunja API token |

Copy `.env.example` to `.env` and fill in your tokens:

```bash
cp .env.example .env
```

## Development

```bash
git clone https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git
cd devx
make setup         # Create venv, install deps, hooks, CI tools
make lint-all      # ruff + pyright + bandit + actionlint
make pytest-cov    # Unit tests with 100% coverage
```

See [AGENTS.md](AGENTS.md) for full project conventions, PR workflow, and architecture details.

## License

GPL-3.0