Metadata-Version: 2.2
Name: fluxy
Version: 0.4.0
Summary: AI-ready workflow contract for software projects.
Author: Jasurbek Kamilov
Maintainer: Fluxy
License: MIT
Project-URL: Homepage, https://pypi.org/project/fluxy/
Project-URL: Issues, https://pypi.org/project/fluxy/
Keywords: cli,developer-tools,automation,workflow,ci,yaml,ai-agents,task-runner
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: rich<14,>=13.7
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# Fluxy

Fluxy is an AI-ready workflow contract for software projects.

It gives a project one clear place to describe how to run, test, validate, and
ship safely. Humans can use it. CI can use it. AI coding agents can use it
without guessing which README command is still correct.

```bash
pip install fluxy
fluxy init
fluxy doctor
fluxy run check
```

## What is Fluxy?

Fluxy is a small command-line tool built around a `fluxy.yml` file.

That file describes the workflows a project supports: linting, tests, builds,
environment checks, release steps, and commands that should not be run without
human confirmation.

Fluxy is not trying to be another general-purpose task runner. The product idea
is higher-level: Fluxy is a contract between a software project, its developers,
CI, and AI agents.

## Why Fluxy?

Most projects start with commands in a README:

```bash
pytest
ruff check .
python -m build
```

Over time those commands drift. The README says one thing, CI runs another,
local scripts do a third thing, and a new developer has to guess what is safe.
AI coding agents have the same problem: they can edit code, but they often do
not know which commands validate the project or which commands are dangerous.

Fluxy turns those commands into an explicit workflow contract:

- define project commands once
- list safe workflows for humans and AI agents
- validate required environment variables without printing secret values
- protect release and deploy tasks behind human confirmation
- make `doctor` the first place to understand project health
- leave room for CI generation from the same contract later

Cursor writes code. Fluxy tells it how to run, test, and ship safely.

## Installation

```bash
pip install fluxy
```

For isolated CLI installation:

```bash
pipx install fluxy
```

## Quick start

Create a workflow file:

```bash
fluxy init
```

Inspect the project:

```bash
fluxy doctor
```

List available workflows:

```bash
fluxy list
```

Run a workflow:

```bash
fluxy run check
```

## Core commands

```bash
fluxy init                 # create fluxy.yml
fluxy list                 # show project workflows
fluxy run <task>           # run a workflow
fluxy run <task> --agent   # only allow agent-safe workflows
fluxy env check            # verify required environment variables
fluxy env check --task release
fluxy doctor               # inspect config, tasks, env, and safety rules
fluxy --version            # show installed version
```

## Python API

Fluxy also exposes a small Python API for tools that want to inspect the same
workflow contract:

```python
from fluxy import check_environment, list_tasks, load_workflow, run

workflow = load_workflow("fluxy.yml")

print(list_tasks(workflow, agent_safe=True))
print(check_environment(workflow))

run(workflow, "check", agent=True)
```

See `docs/API.md` for the public v0.4 API surface.

## Example workflow

```yaml
project: my-python-package

tasks:
  lint:
    description: Run static checks.
    agent_safe: true
    cmd: ruff check .

  test:
    description: Run the test suite.
    agent_safe: true
    cmd: pytest

  check:
    description: Run all local validation before a pull request.
    agent_safe: true
    steps:
      - task: lint
      - task: test

  build:
    description: Build distribution files.
    agent_safe: true
    cmd: python -m build

  release:
    description: Upload the package after human review.
    protected: true
    agent_safe: false
    env:
      - name: PYPI_API_TOKEN
        description: Required only for release.
        secret: true
    steps:
      - task: check
      - task: build
      - run: python -m twine upload dist/*
```

Protected tasks require human confirmation:

```bash
fluxy run release
```

Non-interactive environments can use `--yes` only after an explicit human
decision:

```bash
fluxy run release --yes
```

## AI agents

Fluxy has a first-class idea of agent-safe workflows.

An AI coding agent can run:

```bash
fluxy list --agent-safe
fluxy run check --agent
```

This gives the agent a safe list of commands without relying on README guessing.
If the task is not marked `agent_safe: true`, Fluxy refuses to run it in agent
mode. Protected tasks such as release or deploy are also blocked.

Fluxy does not include telemetry. It does not send project names, paths, command
strings, environment variables, repository URLs, or usage events anywhere.

## Roadmap

Fluxy v0.4.0 is the clean baseline:

- project init
- workflow listing
- task execution
- environment validation
- protected workflows
- agent-safe workflow mode
- doctor report
- professional package metadata and documentation

Future versions may add:

- CI generation from `fluxy.yml`
- richer schema validation
- watch mode
- reusable workflow templates
- safer release profiles

No cloud service, marketplace, hidden telemetry, or paid plan is part of the
v0.4.0 scope.

## License

Fluxy is released under the MIT License.

## Author

Created by Jasurbek Kamilov.

Maintained as the Fluxy open-source project.
