Metadata-Version: 2.4
Name: iomate-pkg-workflow
Version: 0.1.0a0
Summary: IOMate Package providing control-flow and error-handling Actions
License-File: LICENSE
Author: IOMate
Requires-Python: >=3.12,<=3.14.4
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: iomate-base (>=0.1.0a0,<0.2.0)
Description-Content-Type: text/markdown

<div align="center">
  <h1><strong>IOMATE-PKG-WORKFLOW</strong></h1>
</div>

<p align="center">
  <a href="https://github.com/iomateapp/iomate-pkg-workflow/actions?query=branch%staging">
    <img src="https://github.com/iomateapp/iomate-pkg-workflow/actions/workflows/quality-and-tests.yaml/badge.svg?branch=staging" />
  </a>
  <a href="https://codecov.io/gh/iomateapp/iomate-pkg-workflow">
    <img src="https://codecov.io/gh/iomateapp/iomate-pkg-workflow/branch/staging/graph/badge.svg" />
  </a>
  <img src="https://img.shields.io/pypi/dm/iomate-pkg-workflow" />
  <img src="https://img.shields.io/github/license/iomateapp/iomate-pkg-workflow" />
  <img src="https://img.shields.io/github/v/release/iomateapp/iomate-pkg-workflow" />
  <img src="https://img.shields.io/github/stars/iomateapp/iomate-pkg-workflow?style=flat" />
</p>

Control-flow and error-handling Actions for IOMate.

`iomate-pkg-workflow` is an IOMate Package built on top of
[`iomate-base`](https://github.com/roderiano/iomate-base).

It provides Actions for controlling execution flow and handling errors
inside IOMate Automations.

---

## Features

The Package provides two main Action Groups:

```text
Workflow
├── workflow.if
├── workflow.else_if
└── workflow.else

Error Handling
├── error_handling.try
├── error_handling.except
└── error_handling.finally
```

These Actions are designed to integrate with the IOMate runtime and
follow the Action, Variable, and Contract abstractions provided by
`iomate-pkg-workflow`.

---

## Requirements

- Python 3.12+
- Poetry
- `iomate-base`

The supported Python version range is defined in `pyproject.toml`.

---

## Installation

Install from PyPI:

```bash
pip install iomate-pkg-workflow
```

Or add it to a Poetry project:

```bash
poetry add iomate-pkg-workflow
```

The Package requires a compatible version of:

```text
iomate-base
```

---

## Development Setup

Clone the repository and install the development dependencies:

```bash
poetry install
```

Run commands through Poetry:

```bash
poetry run <command>
```

---

## Project Structure

```text
iomate-pkg-workflow/
├── pyproject.toml
├── poetry.lock
│
├── src/
│   └── iomate_pkg_workflow/
│       ├── actions/
│       │   ├── workflow/
│       │   └── error_handling/
│       ├── package.py
│       └── ...
│
├── tests/
│   ├── workflow/
│   ├── error_handling/
│   └── ...
│
├── README.md
├── CONTRIBUTING.md
└── CODE_OF_CONDUCT.md
```

The exact internal structure may evolve as the Package grows, but
Package-specific implementation must remain isolated from
`iomate-base`.

---

## Action Groups

### Workflow

The Workflow group provides conditional control-flow Actions.

```text
workflow.if
workflow.else_if
workflow.else
```

These Actions allow an Automation to select execution paths based on
conditions evaluated during runtime.

Conceptually:

```text
workflow.if
    │
    ├── condition = true
    │       ↓
    │    execute branch
    │
    └── condition = false
            ↓
       evaluate else_if / else
```

---

### Error Handling

The Error Handling group provides Actions for defining error-handling
execution scopes.

```text
error_handling.try
error_handling.except
error_handling.finally
```

Conceptually:

```text
try
 │
 ├── Action
 ├── Action
 └── Action
      │
      ├── success → continue
      │
      └── error → except
                    │
                    └── finally
```

The actual execution semantics are defined by the IOMate runtime and
the Action Contracts exposed by this Package.

---

## Action Contracts

Each Action has a stable key and a versioned contract.

Examples:

```text
workflow.if
workflow.else_if
workflow.else
error_handling.try
error_handling.except
error_handling.finally
```

Action Contracts define the interface consumed by the IOMate runtime,
including:

- Inputs
- Outputs
- Type constraints
- Variable flags
- Contract version
- Execution metadata

Example:

```json
{
  "key": "workflow.if",
  "version": "1.0.0",
  "inputs": [
    {
      "name": "condition",
      "type": "boolean",
      "required": true
    }
  ],
  "outputs": []
}
```

Contract changes must preserve backward compatibility whenever possible.

Breaking changes require an appropriate contract version change.

---

## iomate-pkg-workflow

This Package depends on `iomate-base` for the core IOMate abstractions.

The dependency direction must remain:

```text
iomate-base
     ↑
     │
iomate-pkg-workflow
```

`iomate-pkg-workflow` must not implement its own versions of:

- Variables
- Type Definitions
- Actions
- Action Contracts
- Package Registry
- Runtime abstractions

These capabilities must come from `iomate-base`.

---

## Package Interoperability

The Package must remain independent of other IOMate Packages.

For example, `iomate-pkg-workflow` must not directly depend on:

```text
iomate-pkg-selenium
iomate-pkg-http
iomate-pkg-claude
```

Interoperability between Packages is achieved through the shared
IOMate runtime and Variables defined by `iomate-base`.

```text
iomate-base
        │
        │ Variables
        ▼
    IOMate Runtime
        ▲
        │
        │ Variables
        │
iomate-pkg-workflow
```

This keeps Packages independently installable and reusable.

---

## Testing

Run the complete test suite:

```bash
poetry run pytest
```

Run tests with coverage:

```bash
poetry run pytest --cov=src/iomate_pkg_workflow --cov-report=term
```

The project requires a minimum coverage of:

```text
80%
```

Tests should cover:

- Action registration
- Action discovery
- Action metadata
- Input validation
- Output definitions
- Action Contracts
- Conditional behavior
- Error-handling behavior
- Contract compatibility

---

## Code Quality

Run Ruff:

```bash
poetry run ruff check .
```

Check formatting:

```bash
poetry run ruff format --check .
```

Format the project:

```bash
poetry run ruff format .
```

Run MyPy:

```bash
poetry run mypy src
```

---

## Pre-commit

Install the project's pre-commit hooks:

```bash
poetry run pre-commit install
```

Run all hooks:

```bash
poetry run pre-commit run --all-files
```

Run tests and type checking separately:

```bash
poetry run pytest
poetry run mypy src
```

---

## Documentation

Documentation should be updated when changes affect:

- Action behavior
- Action Contracts
- Inputs
- Outputs
- Type constraints
- Error handling
- Control-flow semantics
- Package configuration
- Compatibility requirements

Public Actions should include clear documentation and type annotations.

---

## Versioning

`iomate-pkg-workflow` follows Semantic Versioning:

```text
MAJOR.MINOR.PATCH
```

Examples:

```text
1.0.0
1.1.0
1.1.1
```

### MAJOR

Breaking changes to public Package behavior or Action Contracts.

### MINOR

Backward-compatible functionality, such as:

- New Actions
- New optional inputs
- New Action Groups

### PATCH

Backward-compatible fixes, such as:

- Bug fixes
- Internal implementation corrections
- Documentation corrections

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for:

- Branching strategy
- Development workflow
- Pull Request requirements
- Testing requirements
- Commit conventions
- Release process

See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for the project's
community standards.

---

## Release Process

Releases are prepared from `staging`.

The general release flow is:

```text
feature branch
      ↓
Pull Request
      ↓
staging
      ↓
release preparation
      ↓
release
      ↓
version/tag
      ↓
PyPI
```

Before publishing a release:

- All CI checks must pass
- Version must be updated according to Semantic Versioning
- Action Contract compatibility must be reviewed
- Package dependencies must be validated
- Release notes should be prepared
- Package artifacts must be validated
- The final version must be tagged in Git

The release artifact is published to PyPI as:

```text
iomate-pkg-workflow
```

---

## License

See [LICENSE](LICENSE) for licensing information.

---

## Architecture

`iomate-pkg-workflow` provides control-flow capabilities to the IOMate
execution system while relying on `iomate-pkg-workflow` for its core contracts.

```text
                    IOMate Runtime
                          │
                          │
                    iomate-pkg-workflow
                          │
                          ▼
              iomate-pkg-workflow
                    │           │
                    │           │
              Workflow      Error Handling
                    │           │
              ┌─────┴─────┐ ┌───┴─────────┐
              │     │     │ │      │      │
             if  else_if else try  except finally
```

The core principles are:

```text
iomate-pkg-workflow → Core Contracts
Package     → Workflow Capabilities
Actions     → Executable Behavior
Variables   → Interoperability
Contracts   → Compatibility
```
