Metadata-Version: 2.4
Name: devware
Version: 0.1.0a1
Summary: Check environment variables and HTTP service readiness before running agent workloads.
Author: Devware
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Devware

Check that an agent's environment is ready before starting a workload.

Devware checks required environment variables and HTTP health endpoints from a
small TOML file. It returns a nonzero exit code when a prerequisite fails, so
you can use it in a terminal, a CI job, or a script that starts an agent.

This first alpha is a local readiness checker. It does not provision runtimes,
execute agents, manage secrets, or call a hosted Devware API.

## Install

Requires Python 3.11 or later. Once this release is published on PyPI:

```sh
python -m pip install 'devware==0.1.0a1'
```

For local development from this source directory:

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/devware --version
```

On Windows, virtual-environment executables are in `.venv\Scripts`.

## Configure

```sh
devware init
```

This creates `devware.toml` and refuses to overwrite an existing file. Edit the
example to match the services your workload actually needs:

```toml
required_env = ["OPENAI_API_KEY"]

[[services]]
name = "application"
url = "http://127.0.0.1:8000/health"
expected_status = 200

[[services]]
name = "retrieval"
url = "http://127.0.0.1:9000/ready"
expected_status = 204
```

`required_env` contains variable names, never their values. A variable passes
when it exists and is not empty. The tool reads the current process environment;
it does not load `.env` files. Configure at least one variable or one service.
`expected_status` defaults to `200` and must match exactly. Variable names and
service names must be unique within their respective lists.

## Check

```sh
devware check
devware check --config environments/local.toml --timeout 5
devware check --json
```

Example human-readable output:

```text
PASS  environment OPENAI_API_KEY: Set
PASS  service application: HTTP 200
FAIL  service retrieval: HTTP 503; expected 204
Not ready. Resolve failed checks before running your workload.
```

JSON output contains `ok` and a `checks` array. Each result includes `kind`,
`name`, `ok`, and `detail`. Configuration errors add an `error` field and return
an empty `checks` array. Environment values, URLs, and response bodies are not
included in reports.

| Exit code | Meaning |
| --- | --- |
| `0` | All configured checks passed, or `init` succeeded |
| `1` | At least one readiness check failed |
| `2` | Invalid arguments/configuration or an unreadable/unwritable file |
| `130` | Checks interrupted by the user |

Use the result to gate an existing command:

```sh
devware check && your-agent-command
```

## HTTP behavior and limits

- Each configured service receives one `GET` request. Use health endpoints that
  are safe to call. Requests run sequentially with no retries.
- Only HTTP and HTTPS URLs are supported. Embedded username/password credentials
  and fragments are rejected. Use ASCII or percent-encoded URLs.
- Redirects are not followed. An HTTP 302 fails unless `302` is explicitly the
  expected status. TLS certificate verification remains enabled.
- Responses are checked by status only. Bodies are not read, printed, or parsed.
- There are no authentication headers, proxy support, or telemetry. Proxy
  environment variables are not used.
- `--timeout` sets the socket timeout per service, from greater than zero to 60
  seconds (default: 3). It is not a total run deadline; OS DNS resolution can
  exceed the socket timeout.
- Checks show readiness at one point in time. They do not guarantee that an
  agent will succeed or that the service will remain healthy.

You can also run the CLI with `python -m devware`.

## Development

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -e . build twine
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m build
.venv/bin/python -m twine check --strict dist/*
```

Tests use a local HTTP server and synthetic environment variables. They do not
call external APIs or require API keys. See `RELEASING.md` before publishing.

## License

MIT. See `LICENSE`.
