Metadata-Version: 2.5
Name: gwrun
Version: 0.0.2
Summary: A tiny, dependency-free runner for GitHub Actions-style workflow files, with an interactive TUI.
Project-URL: Homepage, https://github.com/maximilianharr/gwrun
Project-URL: Issues, https://github.com/maximilianharr/gwrun/issues
Author: ham5st
License-Expression: MIT
License-File: LICENSE
Keywords: ci,github-actions,local-runner,tui,workflow
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# gwrun

A tiny, dependency-free (Python stdlib only) tool to run GitHub Actions-style
workflow `run:` steps locally or on a remote host via SSH, with an optional
interactive TUI to pick which steps to run. See [REQUIREMENTS.md](REQUIREMENTS.md)
for the full design and supported feature scope.

## Install

Recommended (isolated, keeps your global Python environment clean):

```bash
pipx install gwrun
```

Or with plain pip:

```bash
pip install gwrun
```

Works the same way on Windows (PowerShell) and Linux (bash) — both install a
`gwrun` command onto your `PATH`.

## Usage

```bash
gwrun <workflow.yml> [--env FILE] [--secrets FILE] [--remote user@host] [--no-tui]
```

- `<workflow.yml>` — path to the workflow file to run (required)
- `--env` — env file to load (defaults to `.env` in the current directory if present)
- `--secrets` — secrets file to load (defaults to `.env.secrets` in the current directory if present)
- `--remote user@host` — run every step over SSH instead of locally
- `--no-tui` — run all steps directly, even from an interactive terminal

When run from an interactive terminal, `gwrun` opens a TUI to select which
steps to run. When run non-interactively (e.g. in CI), it runs all steps in
order, ignoring saved TUI selections. Explicit `--env` and `--secrets` paths
must exist.

The TUI supports Windows and Linux terminals, including WSL and nested
`machinectl shell` sessions. It updates only changed rows without scrolling
or repeatedly clearing the screen. Use right/left to switch between step
navigation and output scrolling; `q` or Ctrl+C during a run cancels it and
restores the terminal. Quitting after a failed run returns a nonzero exit code.
For plain streaming output, use `--no-tui`.

Only `run:` steps are executed. Selected `uses:` steps report an error and
stop the run; deselect them in the TUI if their setup is already available.
This is not a full GitHub Actions implementation: conditions, dependencies,
matrix expansion, and per-step shells/directories are ignored. YAML is a
restricted subset; unsupported syntax (including flow-style `[]`/`{}` values,
anchors, and multiple documents) is rejected rather than partially executed.
Use block mappings/lists and JSON-compatible escapes in double-quoted strings.

**Run only trusted workflows.** Commands run as your current user, without
sandboxing, in the current working directory. SSH execution requires Bash and
the same directory on the remote host; a missing remote directory fails the
step. Cancelling SSH stops the local client, but remote processes may survive
depending on the server. Literal values from `--secrets` are masked in captured
output and logs; transformed/encoded secrets are not.

## Development

Clone the repo and install in editable mode:

```bash
pip install -e .
```

Run the test suite (stdlib `unittest`, no extra dependencies):

```bash
python -m unittest discover -s test
```

## License

MIT — see [LICENSE](LICENSE).
