Metadata-Version: 2.1
Name: wexample-wex-addon-filestate
Version: 6.2.23
Summary: Integrates wexample-filestate's declarative file-tree reconciliation engine into the wex CLI as a pluggable addon
Author-Email: weeger <contact@wexample.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Project-URL: homepage, https://github.com/wexample/python-wex-addon-app
Requires-Python: >=3.10
Requires-Dist: attrs>=23.1.0
Requires-Dist: cattrs>=23.1.0
Requires-Dist: wexample-wex-core>=30.2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Description-Content-Type: text/markdown

# wex_addon_filestate

Version: 6.2.23

wex-addon-filestate plugs [wexample-filestate](https://github.com/wexample/python-filestate)'s declarative file-tree reconciliation engine into the wex CLI as a first-class addon. It is installed as the Python package `wexample-wex-addon-filestate` and targets developers who work inside a wex project and want file-state management available as wex commands alongside the rest of their CLI tooling.

## Table of Contents

- [Installation](#installation)
- [Quickstart](#quickstart)
- [Tests](#tests)
- [Architecture](#architecture)
- [Integration in the Suite](#integration-in-the-suite)
- [Dependencies](#dependencies)
- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
- [License](#license)
- [About us](#about-us)
- [Known Limitations & Roadmap](#known-limitations--roadmap)
- [Status & Compatibility](#status--compatibility)
- [Useful Links](#useful-links)
- [Migration Notes](#migration-notes)

## Installation

```bash
pip install wexample-wex-addon-filestate
```

Requires Python >=3.10.

## Quickstart

Install the package:

```bash
pip install wexample-wex-addon-filestate
```

The one thing the package provides is `FilestateAddonManager`. Pass it to a wex `Kernel` via `setup()` to register the filestate integration:

```python
from pathlib import Path
from wexample_wex_core.common.kernel import Kernel
from wexample_wex_addon_filestate.filestate_addon_manager import FilestateAddonManager

kernel = Kernel(entrypoint_path=Path(".wex"))
kernel.setup(addons=[FilestateAddonManager])

print("filestate" in kernel.get_addons())  # True
```

`kernel.get_addons()` returns a dict keyed by the short snake-case class name, so `"filestate"` confirms the addon is live. Once registered, the filestate workdir reconciliation engine is active for that kernel instance; any commands the addon registers become available alongside the rest of the CLI tooling through `.wex/bin/app-manager`.

## Tests

This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.

### Installation

First, install the required testing dependencies:
```bash
.venv/bin/python -m pip install pytest pytest-cov
```

### Basic Usage

Run all tests with coverage:
```bash
.venv/bin/python -m pytest --cov --cov-report=html
```

### Common Commands
```bash
# Run tests with coverage for a specific module
.venv/bin/python -m pytest --cov=your_module

# Show which lines are not covered
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing

# Generate an HTML coverage report
.venv/bin/python -m pytest --cov=your_module --cov-report=html

# Combine terminal and HTML reports
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html

# Run specific test file with coverage
.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
```

### Viewing HTML Reports

After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.

### Coverage Threshold

To enforce a minimum coverage percentage:
```bash
.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
```

This will cause the test suite to fail if coverage drops below 80%.

## Architecture

`wexample-wex-addon-filestate` is a thin bridge: it contributes a single class to the wex addon system so that the [wexample-filestate](https://github.com/wexample/python-filestate) reconciliation engine becomes available inside a wex `Kernel`. The package uses a standard `src/` layout and is built with PDM.

### Package layout

```
src/wexample_wex_addon_filestate/
├── filestate_addon_manager.py   # the addon's sole public contribution
└── commands/                    # addon commands (empty; populated as commands are added)
```

Everything callable from the outside lives under `src/wexample_wex_addon_filestate/`.

### FilestateAddonManager

src/wexample_wex_addon_filestate/filestate_addon_manager.py contains the only class the package exports:

```python
class FilestateAddonManager(AbstractAddonManager):
    pass
```

It inherits `AbstractAddonManager` from `wexample-wex-core` without overriding anything. The base class supplies the registration, naming, and lifecycle hooks; the subclass exists to give the wex addon system a concrete, importable symbol that identifies this integration.

### Commands package

src/wexample_wex_addon_filestate/commands/__init__.py is the designated home for any wex commands the addon exposes. It is currently empty, meaning the addon registers with the kernel but adds no commands of its own yet.

### Call path

When a caller registers the addon:

```python
kernel = Kernel(entrypoint_path=Path(".wex"))
kernel.setup(addons=[FilestateAddonManager])
```

`kernel.setup()` instantiates `FilestateAddonManager`, registers it under the key `"filestate"` (derived from the class name by `AbstractAddonManager`), and activates the filestate engine for that kernel. After `setup()`, `kernel.get_addons()["filestate"]` is the live manager instance.

### Wex project infrastructure

The `.wex/` directory holds the project's own wex configuration:

- .wex/bin/app-manager — the local CLI entry point; it locates the `wex` binary (via `$CORE_BIN` or `PATH`) and delegates all arguments to it.
- .wex/python/app_manager/app_workdir.py — extends `PythonPackageWorkdir` to declare the project's two git remotes (GitLab primary, GitHub mirror) and the `main` branch. This is consumed by wex's own tooling, not by the Python package at runtime.

### Dependencies

The runtime graph is deliberately small:

| Package | Role |
|---|---|
| `wexample-wex-core` | supplies `AbstractAddonManager` and the `Kernel` registration protocol |
| `attrs` / `cattrs` | structured-data serialisation, inherited from the core stack |

## Integration in the Suite

This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.

### Related Packages

The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.

Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.

## Dependencies

- attrs: >=23.1.0
- cattrs: >=23.1.0
- wexample-wex-core: >=30.2.0

## Versioning & Compatibility Policy

Wexample packages follow **Semantic Versioning** (SemVer):

- **MAJOR**: Breaking changes
- **MINOR**: New features, backward compatible
- **PATCH**: Bug fixes, backward compatible

We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Free to use in both personal and commercial projects.

## About us

[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.

This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.

Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.

## Known Limitations & Roadmap

Current limitations and planned features are tracked in the GitHub issues.

See the [project roadmap](https://github.com/wexample/python-wex_addon_filestate/issues) for upcoming features and improvements.

## Status & Compatibility

**Maturity**: Production-ready

**Python Support**: >=3.10

**OS Support**: Linux, macOS, Windows

**Status**: Actively maintained

## Useful Links

- **Homepage**: https://github.com/wexample/python-wex-addon-filestate
- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
- **Issue Tracker**: https://github.com/wexample/python-wex-addon-filestate/issues
- **Discussions**: https://github.com/wexample/python-wex-addon-filestate/discussions
- **PyPI**: [pypi.org/project/wexample-wex-addon-filestate](https://pypi.org/project/wexample-wex-addon-filestate/)

## Migration Notes

When upgrading between major versions, refer to the migration guides in the documentation.

Breaking changes are clearly documented with upgrade paths and examples.
