Metadata-Version: 2.4
Name: envs-xmpp
Version: 0.11.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: 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

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.

## Development install

Install the checkout into each bot virtual environment:

```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
│   ├── release/
│   ├── runtime/
│   │   ├── alerts.py
│   │   └── diagnostics.py
│   ├── security/
│   │   └── redaction.py
│   ├── storage/
│   │   ├── archive.py
│   │   ├── files.py
│   │   ├── outbox.py
│   │   └── sqlite.py
│   └── xmpp/
│       ├── 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
    ├── service.py
    ├── systemd.py
    └── venv.py
```

## Stable 0.11 API

Version 0.11 adds 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.  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 keep bot policy such as config migration, database backup/restore and
service hardening local, while shared Git release selection, systemd inspection,
operator confirmation, account/path checks and virtualenv creation 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.

## 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.


## 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 diagnostic state, asynchronous release comparison results, and neutral human-readable duration/byte formatting. Applications keep notification policy, active recovery behavior, severity decisions, concrete health checks and domain-specific labels locally.
