Metadata-Version: 2.5
Name: wspkit
Version: 0.0.1
Summary: The whitespace between your workflow tool and everything that talks to it. A Python library providing the JSON-RPC server for the Workflow Server Protocol (WSP).
Project-URL: Homepage, https://pythonomenology.github.io/wspkit/
Project-URL: Documentation, https://pythonomenology.github.io/wspkit/
Project-URL: Sponsor, https://github.com/sponsors/cjames23
Project-URL: History, https://github.com/pythonomenology/wspkit/releases
Project-URL: Tracker, https://github.com/pythonomenology/wspkit/issues
Project-URL: Source, https://github.com/pythonomenology/wspkit/
Author-email: Cary Hawkins <hawkinscary23@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: environment,workflow
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: tomli; python_version < '3.11'
Description-Content-Type: text/markdown

# wspkit

> The whitespace between your workflow tool and everything that talks to it.

`wspkit` is a Python library and command-line client for the **Workflow Server
Protocol (WSP)** — a small JSON-RPC 2.0 protocol that lets workflow tools
(environment managers, task runners, test runners, and so on) expose their
capabilities to consuming tools through a uniform interface, in the same spirit
as the Language Server Protocol does for editors.

If you build a workflow tool, `wspkit` lets you ship a WSP server with one
import. If you want to talk to one, the bundled `wsp` CLI gives you a working
client out of the box, plus a built-in fallback workflow tool backed by
`venv` so the CLI is useful before any tool is installed.

- [Documentation](https://pythonomenology.github.io/wspkit/)
- [Source](https://github.com/pythonomenology/wspkit/)
- [Issues](https://github.com/pythonomenology/wspkit/issues)

## Highlights

- **Standard JSON-RPC 2.0** over LSP-style `Content-Length` framing on stdio —
  any JSON-RPC client library can talk to a wspkit server.
- **Two integration paths.** Take a runtime dependency and register Python
  callables, or stay decoupled with a TOML/JSON config file that points at
  imports or external commands.
- **Batteries-included CLI.** `wsp` performs the per-call lifecycle
  (`initialize` → method → `shutdown` → `exit`) and translates JSON-RPC errors
  into well-defined exit codes.
- **Working fallback workflow tool.** With no target configured, `wsp` manages
  on-disk virtual environments through `environment/list`, `create`, `get`,
  `delete`, and `execute`, persisted across invocations.
- **Verified by property-based tests.** The dispatcher, framing, lifecycle FSM,
  registry, and error model are exercised under `hypothesis`, with integration
  tests covering the full transport on top.

## Install

```sh
pip install wspkit
```

`wspkit` requires Python 3.10 or newer and has no runtime dependencies on
3.11+ (3.10 pulls in `tomli` for TOML parsing).

## Quickstart

### Use the `wsp` CLI against the built-in fallback

With nothing else configured, the CLI runs the in-process fallback workflow
tool, which uses `venv` to manage environments under
`$WSPKIT_STATE_DIR` (defaults to `$XDG_STATE_HOME/wspkit/fallback/` on POSIX,
`%LOCALAPPDATA%\wspkit\fallback\` on Windows).

```sh
# Create an environment.
wsp environment/create --name scratch --python-version 3.12

# List environments.
wsp environment/list

# Run a command inside one.
echo '{"id":"<env-id>","argv":["python","-V"]}' | wsp environment/execute --params-json -

# Delete it.
wsp environment/delete --id <env-id>
```

### Embed `wspkit` in a workflow tool

```python
import asyncio

from wspkit import Capabilities, HandlerRegistry, run_stdio


def initialize(_params):
    return Capabilities(
        methods=tuple(registry.methods()),
        protocol_version="0.1.0",
    ).to_jsonable()


def list_envs(_params):
    return [
        {"id": "default", "name": "default", "python_version": "3.12"},
    ]


registry = HandlerRegistry()
registry.register("initialize", initialize)
registry.register("shutdown", lambda _params: None)
registry.register("environment/list", list_envs)

raise SystemExit(asyncio.run(run_stdio(registry)))
```

### Or describe a server with a Config_File

If you don't want a runtime dependency on `wspkit`, ship a TOML file that
maps WSP methods to your CLI's subcommands. wspkit renders the request
params into argv with `{name}`-style substitution and constructs the WSP
result per a per-method `result` mode.

```toml
# my-tool.toml
[handlers."environment/list"]
command = ["my-tool", "env", "show", "--json"]
result = "json"

[handlers."environment/create"]
command = ["my-tool", "env", "create", "{name}", "-p", "{python_version}"]
result = "template"
template = { id = "{name}", name = "{name}", python_version = "{python_version}", interpreter_path = "", installed_packages = [], extra = {} }

[handlers."environment/delete"]
command = ["my-tool", "env", "remove", "{id}"]
result = "template"
template = { id = "{id}" }

[handlers."environment/execute"]
command = ["my-tool", "run", "-e", "{id}", "--", "{argv}"]
result = "exec"
```

Then any client can launch it with:

```sh
python -m wspkit --config my-tool.toml
```

`wsp` knows how to drive that too:

```sh
wsp --config my-tool.toml environment/list
```

See [Ship a Config_File](docs/guides/config-file.md) for the full schema
and [Adapt an existing CLI](docs/guides/adapt-cli.md) for a worked
example walking through how Hatch could expose its `env` subcommands as
a WSP server with no Python glue.

## CLI exit codes

| Status | Meaning                                                                  |
|-------:|--------------------------------------------------------------------------|
| `0`    | The call succeeded; the JSON result was written to stdout.               |
| `1`    | The server returned a JSON-RPC error (other than method-not-found), or the call timed out. The error object is on stderr. |
| `2`    | Usage error, or the server reported `-32601` (method unsupported).       |

## Documentation

The full documentation lives in [`docs/`](./docs) and is built with
[Zensical](https://zensical.org/). To preview it locally:

```sh
hatch run docs:serve
```

To build a static site:

```sh
hatch run docs:build
```

The published site is at <https://pythonomenology.github.io/wspkit/>.

## Development

```sh
# Run the test matrix in isolated environments.
hatch test

# Lint and type-check.
hatch check code
hatch check types

# Build the documentation locally.
hatch run docs:serve
```

The test suite uses property-based testing extensively (see
[`tests/property/`](./tests/property/)) and is structured so that pure logic —
the JSON-RPC codec, the lifecycle FSM, the dispatcher, the registry, the error
model — is verified against universal properties before any I/O is wired in.

## License

`wspkit` is released under the [MIT License](./LICENSE).
