Metadata-Version: 2.4
Name: envs-xmpp
Version: 1.1.0
Summary: Shared runtime and deployment primitives for envs.net XMPP bots
Author-email: ~creme <creme@envs.net>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/envs-net/envs-xmpp
Project-URL: Documentation, https://github.com/envs-net/envs-xmpp/blob/main/docs/README.md
Project-URL: Repository, https://github.com/envs-net/envs-xmpp
Project-URL: Issues, https://github.com/envs-net/envs-xmpp/issues
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# envs-xmpp

[![PyPI](https://img.shields.io/pypi/v/envs-xmpp.svg)](https://pypi.org/project/envs-xmpp/)
[![Python](https://img.shields.io/pypi/pyversions/envs-xmpp.svg)](https://pypi.org/project/envs-xmpp/)
[![Quality](https://github.com/envs-net/envs-xmpp/actions/workflows/quality.yml/badge.svg)](https://github.com/envs-net/envs-xmpp/actions/workflows/quality.yml)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0--only-blue.svg)](LICENSE)

Shared technical infrastructure for the envs.net XMPP bots [`envsbot`](https://github.com/envs-net/envsbot) and
[`muc_banbot`](https://github.com/envs-net/muc_banbot).

One distribution intentionally ships two stable Python packages:

- `envs_xmpp_core`: bot-neutral runtime, XMPP, config, storage and release primitives.
- `envs_xmpp_ops`: deployment and operations primitives.

Keeping both in one distribution gives runtime and deployment infrastructure one
version, one repository and one release pipeline while preserving the existing
import APIs used by both bots.

The package contains no bot commands, permissions, database schemas, moderation
logic, plugin systems or bot-specific lifecycle policy.

## Compatibility

- Python 3.12 and 3.13
- GPL-3.0-only
- no mandatory third-party runtime dependencies

The bots themselves remain responsible for dependencies such as Slixmpp.

Shared storage primitives include SQLite integrity checking and safe ZIP member
validation/streaming. Pending room invites use a shared typed model, deduplication, store
state machine and SQL repository while each bot keeps only a thin database-API adapter and
bot-specific notification/join policy. Declarative config-schema primitives provide shared
default/type/range/lifecycle metadata; each bot keeps its domain-specific validation,
reload behavior and operator-facing wording local. Pagination provides a neutral page-slice
model while bot frontends retain their existing command-specific return formats.

## Installation

Install the stable package from PyPI:

```bash
python -m pip install envs-xmpp
python -c "import envs_xmpp_core; print(envs_xmpp_core.__version__)"
```

For development, install a checkout in editable mode:

```bash
python -m pip install -e /path/to/envs-xmpp
```

Existing imports remain valid:

```python
from envs_xmpp_core.runtime.tasks import TaskSupervisor
from envs_xmpp_ops.profile import DeploymentProfile
```

## Package layout

```text
src/
├── envs_xmpp_core/
│   ├── config/
│   ├── pagination.py
│   ├── presentation.py
│   ├── release/
│   ├── runtime/
│   │   ├── alerts.py
│   │   ├── diagnostics.py
│   │   ├── health.py
│   │   └── session.py
│   ├── security/
│   │   └── redaction.py
│   ├── storage/
│   │   ├── archive.py
│   │   ├── files.py
│   │   ├── outbox.py
│   │   └── sqlite.py
│   └── xmpp/
│       ├── affiliations.py
│       ├── avatar.py
│       ├── messaging.py
│       ├── muc_join.py
│       └── occupants.py
└── envs_xmpp_ops/
    ├── accounts.py
    ├── deploy.py
    ├── git.py
    ├── interaction.py
    ├── layout.py
    ├── paths.py
    ├── profile.py
    ├── release_audit.py
    ├── service.py
    ├── systemd.py
    └── venv.py
```

## Stable 1.x API

Version 1.0 formalized package-level convenience imports for the shared infrastructure
introduced during the bot consolidation.  The public surfaces are
`envs_xmpp_core.xmpp`, `envs_xmpp_core.storage`, `envs_xmpp_core.runtime`,
`envs_xmpp_core.security`, and `envs_xmpp_ops`.  Direct module imports remain
supported, so existing consumers do not have to migrate immediately.

The stable shared layer now covers avatar/profile publication, confirmed MUC
joins, normalized occupant identity, message-target/reply routing, durable
outbox storage, operational alert state, redacted diagnostics and deployment
layout discovery. Version 1.1 adds the shared operator-presentation models and renderers for task, status and room inventories. Current development additionally shares XMPP session-generation telemetry and bounded MUC affiliation IQ mechanics while keeping reconnect scheduling and bot policy in the applications. Bot-specific policy, command behavior, moderation, OMEMO, plugin systems and notification wording intentionally remain outside the core.

`envs_xmpp_ops` is designed for thin bot-specific deployment frontends. The
frontends subclass the shared `DeploymentTarget` for common checkout/venv/config/
service coordinates and keep bot policy such as config migration, database
backup/restore and service hardening local. Shared Git release selection,
systemd inspection, operator confirmation, account/path checks, virtualenv
creation and consumer release-state auditing live here.

Fresh installs do not assume that this package is already present. Each bot
ships a tiny stdlib-only bootstrap shim. When the exact required `envs-xmpp`
version is unavailable, that shim creates a versioned cached deployment virtualenv
below `$XDG_CACHE_HOME/envs-xmpp/deploy/` (or `~/.cache/envs-xmpp/deploy/`),
installs the pinned version from PyPI, and re-executes the deployment frontend.
`ENVS_XMPP_DEPLOY_SOURCE` can point at a local checkout or wheel for development
and pre-release testing.

## Documentation

- [Developer guide](https://github.com/envs-net/envs-xmpp/blob/main/docs/development.md)
- [Architecture and ownership boundaries](https://github.com/envs-net/envs-xmpp/blob/main/docs/architecture.md)
- [Stable API reference](https://github.com/envs-net/envs-xmpp/blob/main/docs/api.md)
- [Consolidation policy](https://github.com/envs-net/envs-xmpp/blob/main/docs/consolidation-policy.md)

The documentation intentionally distinguishes stable public imports from internal
implementation details. Bot-specific policy should stay in the applications unless
it has demonstrably identical semantics in more than one consumer.

## CI and PyPI releases

GitHub Actions tests Python 3.12 and 3.13. A `vX.Y.Z` tag is accepted only when
it exactly matches `project.version` in `pyproject.toml`. Release distributions
are published through PyPI Trusted Publishing/OIDC, without a long-lived PyPI
token.

PyPI publishing is configured through the `pypi` GitHub environment and the
Trusted Publisher for `envs-net/envs-xmpp` using `.github/workflows/release.yml`.

## Shared developer quality runners

`envs_xmpp_ops.quality` and `envs_xmpp_ops.testing` provide the common local
quality/test frontends used by envsbot and muc_banbot. Project-specific source
targets, generated-file checks, integration markers and coverage floors remain
declarative in each repository's `pyproject.toml`; the runner behavior and gate
ordering stay shared.

The quality runner enforces a common baseline: compilation, project validation,
warning-strict tests, Ruff repository/F401/I-UP-B gates, mypy, Git whitespace
validation and dependency audit. Consumer project validation can include
`python -m envs_xmpp_ops.release_audit`, which verifies that package metadata,
requirements, constraints and the deploy bootstrap agree on one shared-core
version before a release is cut.


## Runtime and utility primitives

The shared core also provides heartbeat-aware worker waits, lifecycle phase orchestration, passive `HealthCheck`/`HealthSnapshot` diagnostics with failure-isolated collection, normalized task/watchdog/lifecycle/room-inventory facts, ordered health-message flattening, asynchronous release comparison results, and neutral human-readable duration/byte formatting. Applications keep notification policy, active recovery behavior, severity decisions, concrete domain checks and labels locally.
