Metadata-Version: 2.4
Name: flowsh-cli
Version: 0.7.2
Summary: Generate Bash harness scripts from workflow YAML files.
License-Expression: MIT
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: pyyaml>=6,<7
Requires-Dist: pydantic>=2,<3
Requires-Dist: typer>=0.20,<0.21
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/tbrandenburg/flowsh
Project-URL: Source, https://github.com/tbrandenburg/flowsh
Description-Content-Type: text/markdown

# flowsh-cli

`flowsh-cli` turns workflow YAML into executable Bash harnesses for OpenCode.

Use it when you want a small, reproducible way to encode a workflow once and rerun it locally or in CI.

## Quick Start

```bash
uvx flowsh-cli path/to/workflows.yml
```

That reads the workflow YAML at the path you provide and writes harnesses under `.harness/`.

In this repository, the example workflow file lives at `.made/workflows.yml`.

Useful flags:

```bash
uvx flowsh-cli path/to/workflows.yml --dry-run
uvx flowsh-cli path/to/workflows.yml --workflow wf_example
uvx flowsh-cli path/to/workflows.yml --force
uvx flowsh-cli path/to/workflows.yml --schema
uvx flowsh-cli --examples
uvx flowsh-cli --example simple
```

You can also run it locally with `uv run flowsh-cli`.

## Workflow Shape

The input file is a single mapping with a `workflows` list:

```yaml
workflows:
  - id: wf_example
    name: Example
    params:
      - name: ISSUE_NUMBER
        description: Issue to inspect
        required: true
    steps:
      - type: vars
        values:
          TODAY: date -u +%F
      - type: bash
        run: printf 'today=%s\n' "$TODAY"
      - type: agent
        agent: general
        model: openai/gpt-5
        command: review
        expandPrompt: true
        prompt: |
          Review issue ${ISSUE_NUMBER} and summarize the repository state.
      - type: parallel
        steps:
          - type: bash
            run: echo "worker A"
          - type: bash
            run: echo "worker B"
      - type: for
        in: ITEMS
        item: ITEM
        steps:
          - type: bash
            run: echo "$ITEM"
```

Harness paths are derived from workflow ids. `wf_example` becomes `.harness/example.sh`.

## Step Types

| Type | Purpose | Notes |
|---|---|---|
| `vars` | Capture command output into exported shell variables | Variable names must be uppercase shell identifiers. |
| `bash` | Run shell commands | Runs with `bash -euo pipefail`. |
| `agent` | Call OpenCode | Supports `agent`, `model`, `command`, `expandPrompt`, and `dangerouslySkipPermissions`. |
| `for` | Iterate over newline-delimited input | Flat iteration only; nested `for` steps are not supported. |
| `parallel` | Run child steps concurrently | Children run as separate branches and the parent waits for all of them. |

## Agent Behavior

`agent` prompts are literal by default. Use `expandPrompt: true` only when you want `$VAR` or `${VAR}` tokens from earlier `vars` steps substituted at runtime.

`expandPrompt: true` does plain text replacement only. It does not evaluate shell expressions like `$(...)`, backticks, or globs.

Set `dangerouslySkipPermissions: true` only when you want the generated harness to pass `--dangerously-skip-permissions` to OpenCode. The YAML alias `dangerously-skip-permissions` is also accepted.

## Validation And Safety

The parser is strict:

- workflow YAML must be UTF-8, non-empty, and under 1 MiB
- the root must be a mapping with a `workflows` key
- duplicate mapping keys and YAML aliases are rejected
- workflow ids must match `wf_[A-Za-z0-9_-]+`
- workflow and step names must be non-empty single-line labels
- unsafe control characters are rejected in executable fields
- `agent` names may contain only letters, digits, `_`, and `-`

Generated harnesses are non-interactive, owner-executable, and refuse to overwrite existing outputs unless `--force` is set.

Logs go to `.flowsh/logs` by default. Set `FLOWSH_LOG_DIR` to use another relative log directory.

## Development

```bash
uv sync
make install
make qa
make clean
```

`make qa` runs linting, tests, and a local build.

## Release

```bash
make bump-patch
```

That bumps the patch version, runs QA, and publishes the package.

## Limits

This repository intentionally stays focused on the Python CLI blueprint. It does not include the old TypeScript implementation, workflow templates, DSL explorer, plugin registry, or extra workflow node types.
