flowsh-cli 0.7.0__tar.gz → 0.7.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- flowsh_cli-0.7.2/PKG-INFO +142 -0
- flowsh_cli-0.7.2/README.md +126 -0
- {flowsh_cli-0.7.0 → flowsh_cli-0.7.2}/pyproject.toml +1 -1
- {flowsh_cli-0.7.0 → flowsh_cli-0.7.2}/src/flowsh_cli/__init__.py +1 -1
- {flowsh_cli-0.7.0 → flowsh_cli-0.7.2}/src/flowsh_cli/cli.py +1 -1
- flowsh_cli-0.7.0/PKG-INFO +0 -162
- flowsh_cli-0.7.0/README.md +0 -146
- {flowsh_cli-0.7.0 → flowsh_cli-0.7.2}/src/flowsh_cli/__main__.py +0 -0
- {flowsh_cli-0.7.0 → flowsh_cli-0.7.2}/src/flowsh_cli/examples.py +0 -0
- {flowsh_cli-0.7.0 → flowsh_cli-0.7.2}/src/flowsh_cli/models.py +0 -0
- {flowsh_cli-0.7.0 → flowsh_cli-0.7.2}/src/flowsh_cli/render.py +0 -0
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: flowsh-cli
|
|
3
|
+
Version: 0.7.2
|
|
4
|
+
Summary: Generate Bash harness scripts from workflow YAML files.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
7
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
8
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
9
|
+
Requires-Dist: pyyaml>=6,<7
|
|
10
|
+
Requires-Dist: pydantic>=2,<3
|
|
11
|
+
Requires-Dist: typer>=0.20,<0.21
|
|
12
|
+
Requires-Python: >=3.11
|
|
13
|
+
Project-URL: Homepage, https://github.com/tbrandenburg/flowsh
|
|
14
|
+
Project-URL: Source, https://github.com/tbrandenburg/flowsh
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
|
|
17
|
+
# flowsh-cli
|
|
18
|
+
|
|
19
|
+
`flowsh-cli` turns workflow YAML into executable Bash harnesses for OpenCode.
|
|
20
|
+
|
|
21
|
+
Use it when you want a small, reproducible way to encode a workflow once and rerun it locally or in CI.
|
|
22
|
+
|
|
23
|
+
## Quick Start
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
uvx flowsh-cli path/to/workflows.yml
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
That reads the workflow YAML at the path you provide and writes harnesses under `.harness/`.
|
|
30
|
+
|
|
31
|
+
In this repository, the example workflow file lives at `.made/workflows.yml`.
|
|
32
|
+
|
|
33
|
+
Useful flags:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
uvx flowsh-cli path/to/workflows.yml --dry-run
|
|
37
|
+
uvx flowsh-cli path/to/workflows.yml --workflow wf_example
|
|
38
|
+
uvx flowsh-cli path/to/workflows.yml --force
|
|
39
|
+
uvx flowsh-cli path/to/workflows.yml --schema
|
|
40
|
+
uvx flowsh-cli --examples
|
|
41
|
+
uvx flowsh-cli --example simple
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
You can also run it locally with `uv run flowsh-cli`.
|
|
45
|
+
|
|
46
|
+
## Workflow Shape
|
|
47
|
+
|
|
48
|
+
The input file is a single mapping with a `workflows` list:
|
|
49
|
+
|
|
50
|
+
```yaml
|
|
51
|
+
workflows:
|
|
52
|
+
- id: wf_example
|
|
53
|
+
name: Example
|
|
54
|
+
params:
|
|
55
|
+
- name: ISSUE_NUMBER
|
|
56
|
+
description: Issue to inspect
|
|
57
|
+
required: true
|
|
58
|
+
steps:
|
|
59
|
+
- type: vars
|
|
60
|
+
values:
|
|
61
|
+
TODAY: date -u +%F
|
|
62
|
+
- type: bash
|
|
63
|
+
run: printf 'today=%s\n' "$TODAY"
|
|
64
|
+
- type: agent
|
|
65
|
+
agent: general
|
|
66
|
+
model: openai/gpt-5
|
|
67
|
+
command: review
|
|
68
|
+
expandPrompt: true
|
|
69
|
+
prompt: |
|
|
70
|
+
Review issue ${ISSUE_NUMBER} and summarize the repository state.
|
|
71
|
+
- type: parallel
|
|
72
|
+
steps:
|
|
73
|
+
- type: bash
|
|
74
|
+
run: echo "worker A"
|
|
75
|
+
- type: bash
|
|
76
|
+
run: echo "worker B"
|
|
77
|
+
- type: for
|
|
78
|
+
in: ITEMS
|
|
79
|
+
item: ITEM
|
|
80
|
+
steps:
|
|
81
|
+
- type: bash
|
|
82
|
+
run: echo "$ITEM"
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Harness paths are derived from workflow ids. `wf_example` becomes `.harness/example.sh`.
|
|
86
|
+
|
|
87
|
+
## Step Types
|
|
88
|
+
|
|
89
|
+
| Type | Purpose | Notes |
|
|
90
|
+
|---|---|---|
|
|
91
|
+
| `vars` | Capture command output into exported shell variables | Variable names must be uppercase shell identifiers. |
|
|
92
|
+
| `bash` | Run shell commands | Runs with `bash -euo pipefail`. |
|
|
93
|
+
| `agent` | Call OpenCode | Supports `agent`, `model`, `command`, `expandPrompt`, and `dangerouslySkipPermissions`. |
|
|
94
|
+
| `for` | Iterate over newline-delimited input | Flat iteration only; nested `for` steps are not supported. |
|
|
95
|
+
| `parallel` | Run child steps concurrently | Children run as separate branches and the parent waits for all of them. |
|
|
96
|
+
|
|
97
|
+
## Agent Behavior
|
|
98
|
+
|
|
99
|
+
`agent` prompts are literal by default. Use `expandPrompt: true` only when you want `$VAR` or `${VAR}` tokens from earlier `vars` steps substituted at runtime.
|
|
100
|
+
|
|
101
|
+
`expandPrompt: true` does plain text replacement only. It does not evaluate shell expressions like `$(...)`, backticks, or globs.
|
|
102
|
+
|
|
103
|
+
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.
|
|
104
|
+
|
|
105
|
+
## Validation And Safety
|
|
106
|
+
|
|
107
|
+
The parser is strict:
|
|
108
|
+
|
|
109
|
+
- workflow YAML must be UTF-8, non-empty, and under 1 MiB
|
|
110
|
+
- the root must be a mapping with a `workflows` key
|
|
111
|
+
- duplicate mapping keys and YAML aliases are rejected
|
|
112
|
+
- workflow ids must match `wf_[A-Za-z0-9_-]+`
|
|
113
|
+
- workflow and step names must be non-empty single-line labels
|
|
114
|
+
- unsafe control characters are rejected in executable fields
|
|
115
|
+
- `agent` names may contain only letters, digits, `_`, and `-`
|
|
116
|
+
|
|
117
|
+
Generated harnesses are non-interactive, owner-executable, and refuse to overwrite existing outputs unless `--force` is set.
|
|
118
|
+
|
|
119
|
+
Logs go to `.flowsh/logs` by default. Set `FLOWSH_LOG_DIR` to use another relative log directory.
|
|
120
|
+
|
|
121
|
+
## Development
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
uv sync
|
|
125
|
+
make install
|
|
126
|
+
make qa
|
|
127
|
+
make clean
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
`make qa` runs linting, tests, and a local build.
|
|
131
|
+
|
|
132
|
+
## Release
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
make bump-patch
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
That bumps the patch version, runs QA, and publishes the package.
|
|
139
|
+
|
|
140
|
+
## Limits
|
|
141
|
+
|
|
142
|
+
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.
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# flowsh-cli
|
|
2
|
+
|
|
3
|
+
`flowsh-cli` turns workflow YAML into executable Bash harnesses for OpenCode.
|
|
4
|
+
|
|
5
|
+
Use it when you want a small, reproducible way to encode a workflow once and rerun it locally or in CI.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
uvx flowsh-cli path/to/workflows.yml
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
That reads the workflow YAML at the path you provide and writes harnesses under `.harness/`.
|
|
14
|
+
|
|
15
|
+
In this repository, the example workflow file lives at `.made/workflows.yml`.
|
|
16
|
+
|
|
17
|
+
Useful flags:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
uvx flowsh-cli path/to/workflows.yml --dry-run
|
|
21
|
+
uvx flowsh-cli path/to/workflows.yml --workflow wf_example
|
|
22
|
+
uvx flowsh-cli path/to/workflows.yml --force
|
|
23
|
+
uvx flowsh-cli path/to/workflows.yml --schema
|
|
24
|
+
uvx flowsh-cli --examples
|
|
25
|
+
uvx flowsh-cli --example simple
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
You can also run it locally with `uv run flowsh-cli`.
|
|
29
|
+
|
|
30
|
+
## Workflow Shape
|
|
31
|
+
|
|
32
|
+
The input file is a single mapping with a `workflows` list:
|
|
33
|
+
|
|
34
|
+
```yaml
|
|
35
|
+
workflows:
|
|
36
|
+
- id: wf_example
|
|
37
|
+
name: Example
|
|
38
|
+
params:
|
|
39
|
+
- name: ISSUE_NUMBER
|
|
40
|
+
description: Issue to inspect
|
|
41
|
+
required: true
|
|
42
|
+
steps:
|
|
43
|
+
- type: vars
|
|
44
|
+
values:
|
|
45
|
+
TODAY: date -u +%F
|
|
46
|
+
- type: bash
|
|
47
|
+
run: printf 'today=%s\n' "$TODAY"
|
|
48
|
+
- type: agent
|
|
49
|
+
agent: general
|
|
50
|
+
model: openai/gpt-5
|
|
51
|
+
command: review
|
|
52
|
+
expandPrompt: true
|
|
53
|
+
prompt: |
|
|
54
|
+
Review issue ${ISSUE_NUMBER} and summarize the repository state.
|
|
55
|
+
- type: parallel
|
|
56
|
+
steps:
|
|
57
|
+
- type: bash
|
|
58
|
+
run: echo "worker A"
|
|
59
|
+
- type: bash
|
|
60
|
+
run: echo "worker B"
|
|
61
|
+
- type: for
|
|
62
|
+
in: ITEMS
|
|
63
|
+
item: ITEM
|
|
64
|
+
steps:
|
|
65
|
+
- type: bash
|
|
66
|
+
run: echo "$ITEM"
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Harness paths are derived from workflow ids. `wf_example` becomes `.harness/example.sh`.
|
|
70
|
+
|
|
71
|
+
## Step Types
|
|
72
|
+
|
|
73
|
+
| Type | Purpose | Notes |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| `vars` | Capture command output into exported shell variables | Variable names must be uppercase shell identifiers. |
|
|
76
|
+
| `bash` | Run shell commands | Runs with `bash -euo pipefail`. |
|
|
77
|
+
| `agent` | Call OpenCode | Supports `agent`, `model`, `command`, `expandPrompt`, and `dangerouslySkipPermissions`. |
|
|
78
|
+
| `for` | Iterate over newline-delimited input | Flat iteration only; nested `for` steps are not supported. |
|
|
79
|
+
| `parallel` | Run child steps concurrently | Children run as separate branches and the parent waits for all of them. |
|
|
80
|
+
|
|
81
|
+
## Agent Behavior
|
|
82
|
+
|
|
83
|
+
`agent` prompts are literal by default. Use `expandPrompt: true` only when you want `$VAR` or `${VAR}` tokens from earlier `vars` steps substituted at runtime.
|
|
84
|
+
|
|
85
|
+
`expandPrompt: true` does plain text replacement only. It does not evaluate shell expressions like `$(...)`, backticks, or globs.
|
|
86
|
+
|
|
87
|
+
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.
|
|
88
|
+
|
|
89
|
+
## Validation And Safety
|
|
90
|
+
|
|
91
|
+
The parser is strict:
|
|
92
|
+
|
|
93
|
+
- workflow YAML must be UTF-8, non-empty, and under 1 MiB
|
|
94
|
+
- the root must be a mapping with a `workflows` key
|
|
95
|
+
- duplicate mapping keys and YAML aliases are rejected
|
|
96
|
+
- workflow ids must match `wf_[A-Za-z0-9_-]+`
|
|
97
|
+
- workflow and step names must be non-empty single-line labels
|
|
98
|
+
- unsafe control characters are rejected in executable fields
|
|
99
|
+
- `agent` names may contain only letters, digits, `_`, and `-`
|
|
100
|
+
|
|
101
|
+
Generated harnesses are non-interactive, owner-executable, and refuse to overwrite existing outputs unless `--force` is set.
|
|
102
|
+
|
|
103
|
+
Logs go to `.flowsh/logs` by default. Set `FLOWSH_LOG_DIR` to use another relative log directory.
|
|
104
|
+
|
|
105
|
+
## Development
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
uv sync
|
|
109
|
+
make install
|
|
110
|
+
make qa
|
|
111
|
+
make clean
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
`make qa` runs linting, tests, and a local build.
|
|
115
|
+
|
|
116
|
+
## Release
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
make bump-patch
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
That bumps the patch version, runs QA, and publishes the package.
|
|
123
|
+
|
|
124
|
+
## Limits
|
|
125
|
+
|
|
126
|
+
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.
|
|
@@ -35,7 +35,7 @@ def main(argv: Sequence[str] | None = None) -> int:
|
|
|
35
35
|
|
|
36
36
|
@app.command(help="Generate reproducible OpenCode Bash harness scripts from MADE workflow YAML.")
|
|
37
37
|
def generate(
|
|
38
|
-
workflow_yaml: Annotated[Path, typer.Argument(help="Path to
|
|
38
|
+
workflow_yaml: Annotated[Path, typer.Argument(help="Path to workflow YAML")],
|
|
39
39
|
workflow: Annotated[
|
|
40
40
|
str | None,
|
|
41
41
|
typer.Option(
|
flowsh_cli-0.7.0/PKG-INFO
DELETED
|
@@ -1,162 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: flowsh-cli
|
|
3
|
-
Version: 0.7.0
|
|
4
|
-
Summary: Generate Bash harness scripts from workflow YAML files.
|
|
5
|
-
License-Expression: MIT
|
|
6
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
7
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
8
|
-
Classifier: Programming Language :: Python :: 3.13
|
|
9
|
-
Requires-Dist: pyyaml>=6,<7
|
|
10
|
-
Requires-Dist: pydantic>=2,<3
|
|
11
|
-
Requires-Dist: typer>=0.20,<0.21
|
|
12
|
-
Requires-Python: >=3.11
|
|
13
|
-
Project-URL: Homepage, https://github.com/tbrandenburg/flowsh
|
|
14
|
-
Project-URL: Source, https://github.com/tbrandenburg/flowsh
|
|
15
|
-
Description-Content-Type: text/markdown
|
|
16
|
-
|
|
17
|
-
# flowsh-cli
|
|
18
|
-
|
|
19
|
-
`flowsh-cli` is a small `uv` Python CLI that reads workflow YAML and writes executable Bash harness scripts for OpenCode.
|
|
20
|
-
|
|
21
|
-
## Supported YAML
|
|
22
|
-
|
|
23
|
-
Only this top-level shape is supported:
|
|
24
|
-
|
|
25
|
-
```yaml
|
|
26
|
-
workflows:
|
|
27
|
-
- id: wf_example
|
|
28
|
-
name: Example
|
|
29
|
-
steps:
|
|
30
|
-
- type: vars
|
|
31
|
-
name: Capture date
|
|
32
|
-
values:
|
|
33
|
-
TODAY: date -u +%F
|
|
34
|
-
- type: bash
|
|
35
|
-
name: Print date
|
|
36
|
-
run: |
|
|
37
|
-
printf 'today=%s\n' "$TODAY"
|
|
38
|
-
- type: agent
|
|
39
|
-
name: Ask OpenCode
|
|
40
|
-
agent: general
|
|
41
|
-
model: openai/gpt-5
|
|
42
|
-
command: review
|
|
43
|
-
prompt: |
|
|
44
|
-
Summarize the current repository state.
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
Supported step types are only `vars`, `bash`, and `agent`.
|
|
48
|
-
|
|
49
|
-
The input path must be a regular file no larger than 1 MiB. The input file must be valid UTF-8, non-empty YAML with a mapping root, no duplicate mapping keys, and no YAML aliases. Workflow and step names are single-line labels. Executable fields reject unsafe control bytes while allowing normal newlines and tabs. `vars` keys must be uppercase shell variable names, and `agent` names may contain only letters, digits, `_`, and `-`. Agent `model` values are passed through to OpenCode, so provider/model IDs such as `openai/gpt-5` are valid. Agent `command` values map to OpenCode `--command`; the prompt remains the message/arguments after `--`.
|
|
50
|
-
|
|
51
|
-
Agent prompts are literal by default. Set `expandPrompt: true` on an `agent` step only when the prompt should be expanded by Bash at harness runtime, for example to insert values exported by earlier `vars` steps:
|
|
52
|
-
|
|
53
|
-
```yaml
|
|
54
|
-
- type: agent
|
|
55
|
-
name: Fix captured issue
|
|
56
|
-
agent: general
|
|
57
|
-
expandPrompt: true
|
|
58
|
-
prompt: |
|
|
59
|
-
Follow issue #$ISSUE_NUMBER.
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
`expandPrompt: true` is a security-sensitive opt-in: Bash also performs command substitution such as `$(...)` and backticks in the prompt body before OpenCode receives it. Keep it disabled for prompts that contain shell examples or untrusted content.
|
|
63
|
-
|
|
64
|
-
Set `dangerouslySkipPermissions: true` on an `agent` step only when the generated harness should pass OpenCode `--dangerously-skip-permissions`. The flag is false by default, accepts the YAML alias `dangerously-skip-permissions`, and auto-approves permissions that are not explicitly denied. Treat it as security-sensitive and avoid it for untrusted workflows.
|
|
65
|
-
|
|
66
|
-
Harness paths are derived from workflow ids. `wf_example` writes `.harness/example.sh`.
|
|
67
|
-
|
|
68
|
-
## Commands
|
|
69
|
-
|
|
70
|
-
```bash
|
|
71
|
-
# Generate every workflow harness
|
|
72
|
-
uvx flowsh-cli .made/workflows.yml
|
|
73
|
-
|
|
74
|
-
# Generate one workflow by id
|
|
75
|
-
uvx flowsh-cli .made/workflows.yml --workflow wf_example
|
|
76
|
-
|
|
77
|
-
# Show planned outputs without writing files
|
|
78
|
-
uvx flowsh-cli .made/workflows.yml --dry-run
|
|
79
|
-
|
|
80
|
-
# Overwrite existing harness files
|
|
81
|
-
uvx flowsh-cli .made/workflows.yml --force
|
|
82
|
-
|
|
83
|
-
# Show version
|
|
84
|
-
uvx flowsh-cli --version
|
|
85
|
-
|
|
86
|
-
# Show the workflow YAML schema
|
|
87
|
-
uvx flowsh-cli --schema
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
You can also run it via `uv run flowsh-cli` if installed locally.
|
|
91
|
-
|
|
92
|
-
## CLI Contract
|
|
93
|
-
|
|
94
|
-
`flowsh-cli` is non-interactive. It never prompts for missing information.
|
|
95
|
-
|
|
96
|
-
Current help output is plain text and deterministic across repeated runs:
|
|
97
|
-
|
|
98
|
-
```text
|
|
99
|
-
Usage: flowsh-cli [OPTIONS] WORKFLOW_YAML
|
|
100
|
-
|
|
101
|
-
Generate reproducible OpenCode Bash harness scripts from MADE workflow YAML.
|
|
102
|
-
|
|
103
|
-
Arguments:
|
|
104
|
-
WORKFLOW_YAML Path to .made/workflows.yml \[required]
|
|
105
|
-
|
|
106
|
-
Options:
|
|
107
|
-
--workflow TEXT Optional workflow id to generate. Defaults to all workflows.
|
|
108
|
-
--dry-run Print planned output paths without writing scripts.
|
|
109
|
-
--force Overwrite existing files. Without this, existing files cause a failure.
|
|
110
|
-
--version Show the flowsh-cli version and exit.
|
|
111
|
-
--schema Show the workflow YAML schema and exit.
|
|
112
|
-
--help Show this message and exit.
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
The CLI pins its help formatter width so this contract does not vary with the
|
|
116
|
-
caller terminal size or `COLUMNS` environment value.
|
|
117
|
-
|
|
118
|
-
Exit codes:
|
|
119
|
-
|
|
120
|
-
| Case | Exit | stdout | stderr |
|
|
121
|
-
|---|---:|---|---|
|
|
122
|
-
| `--help` | `0` | Help text | Empty |
|
|
123
|
-
| `--version` | `0` | `flowsh-cli <version>` | Empty |
|
|
124
|
-
| `--schema` | `0` | Workflow schema as YAML-formatted JSON Schema | Empty |
|
|
125
|
-
| Valid generation | `0` | One `Wrote <path>` line per harness | Empty |
|
|
126
|
-
| Valid `--dry-run` | `0` | One `DRY-RUN would write <path>` line per selected workflow | Empty |
|
|
127
|
-
| Missing required CLI argument | `2` | Empty | Typer usage error |
|
|
128
|
-
| Malformed or unsupported workflow YAML | `1` | Empty | `ERROR: <reason>` |
|
|
129
|
-
| Unknown `--workflow` id | `1` | Empty | `ERROR: No workflow id matched ...` with known workflow ids |
|
|
130
|
-
| Existing harness without `--force` | `1` | Empty | `ERROR: Refusing to overwrite ...` |
|
|
131
|
-
| Output directory/path safety failure | `1` | Empty | `ERROR: <path safety reason>` |
|
|
132
|
-
|
|
133
|
-
Generated harnesses are also non-interactive. `harness.sh --dry-run` exits `0` after logging planned steps to stderr and creating no log directory. A real harness run exits `0` only after every step succeeds. Failed `bash`, `vars`, or `agent` steps return the failing command status, log `Step failed: <step> (exit=<code>)` to stderr, and stop before later steps run. If an `agent` step runs without `opencode` on `PATH`, the harness exits `127` and prints `opencode CLI not found in PATH` to stderr.
|
|
134
|
-
|
|
135
|
-
Generated harnesses are written with owner-only executable permissions and refuse to overwrite existing paths unless `--force` is passed. Multi-workflow generation preflights overwrite conflicts before writing any harness. `--force` replaces regular harness files and harness-file symlinks, but never replaces a directory at a harness file path. The `.harness` output directory must be a real directory, not a symlink or file. Harness dry runs do not create log files or directories. Real harness logs go to `.flowsh/logs` by default with owner-private directory and file permissions. Set `FLOWSH_LOG_DIR` when running a harness to use another local relative log directory; absolute paths, `..` path segments, symlinked path components, and non-directory log paths are refused. Logging setup and write failures fail the harness instead of being silently ignored.
|
|
136
|
-
|
|
137
|
-
Generated `bash` and `vars` bodies run with `bash -euo pipefail`, so command failures stop the workflow instead of being masked by later successful commands. Captured `vars` values are exported for later `bash` steps. `agent` prompt heredocs are quoted by default and unquoted only when `expandPrompt: true` is set. `agent` steps invoke only `opencode run --format json` with optional `--agent <agent>`, `--model <provider/model>`, `--command <command>`, and `--dangerously-skip-permissions` flags before `-- <prompt>`, so dash-prefixed prompts are message content rather than OpenCode flags. Agent steps fail with a clear error if `opencode` is not on `PATH`.
|
|
138
|
-
|
|
139
|
-
## Development
|
|
140
|
-
|
|
141
|
-
```bash
|
|
142
|
-
uv sync
|
|
143
|
-
make install
|
|
144
|
-
make build
|
|
145
|
-
make qa
|
|
146
|
-
make hygiene
|
|
147
|
-
make clean
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
`make install` installs `flowsh-cli` into the user PATH with `uv tool install --force .`.
|
|
151
|
-
`make build` creates reproducible source and wheel distributions under ignored `dist/`.
|
|
152
|
-
|
|
153
|
-
`make qa` runs Ruff, Python compile checks, and pytest with locked dependencies, then builds packages locally and in CI.
|
|
154
|
-
The pytest suite also verifies `python -m flowsh_cli`, `uvx flowsh-cli`, and the direct
|
|
155
|
-
`scripts/workflow_to_harness.py` entrypoint against the same help contract.
|
|
156
|
-
`make hygiene` prints tracked, untracked, and ignored files with
|
|
157
|
-
`git status --short --ignored`; review it before release to confirm only intended
|
|
158
|
-
source changes are present and generated artifacts remain ignored. `make clean`
|
|
159
|
-
removes local caches, build outputs, generated harnesses, and generated logs.
|
|
160
|
-
|
|
161
|
-
There is no TypeScript compiler, template system, DSL explorer, legacy node
|
|
162
|
-
registry, or archived legacy workflow spec in this repository.
|
flowsh_cli-0.7.0/README.md
DELETED
|
@@ -1,146 +0,0 @@
|
|
|
1
|
-
# flowsh-cli
|
|
2
|
-
|
|
3
|
-
`flowsh-cli` is a small `uv` Python CLI that reads workflow YAML and writes executable Bash harness scripts for OpenCode.
|
|
4
|
-
|
|
5
|
-
## Supported YAML
|
|
6
|
-
|
|
7
|
-
Only this top-level shape is supported:
|
|
8
|
-
|
|
9
|
-
```yaml
|
|
10
|
-
workflows:
|
|
11
|
-
- id: wf_example
|
|
12
|
-
name: Example
|
|
13
|
-
steps:
|
|
14
|
-
- type: vars
|
|
15
|
-
name: Capture date
|
|
16
|
-
values:
|
|
17
|
-
TODAY: date -u +%F
|
|
18
|
-
- type: bash
|
|
19
|
-
name: Print date
|
|
20
|
-
run: |
|
|
21
|
-
printf 'today=%s\n' "$TODAY"
|
|
22
|
-
- type: agent
|
|
23
|
-
name: Ask OpenCode
|
|
24
|
-
agent: general
|
|
25
|
-
model: openai/gpt-5
|
|
26
|
-
command: review
|
|
27
|
-
prompt: |
|
|
28
|
-
Summarize the current repository state.
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
Supported step types are only `vars`, `bash`, and `agent`.
|
|
32
|
-
|
|
33
|
-
The input path must be a regular file no larger than 1 MiB. The input file must be valid UTF-8, non-empty YAML with a mapping root, no duplicate mapping keys, and no YAML aliases. Workflow and step names are single-line labels. Executable fields reject unsafe control bytes while allowing normal newlines and tabs. `vars` keys must be uppercase shell variable names, and `agent` names may contain only letters, digits, `_`, and `-`. Agent `model` values are passed through to OpenCode, so provider/model IDs such as `openai/gpt-5` are valid. Agent `command` values map to OpenCode `--command`; the prompt remains the message/arguments after `--`.
|
|
34
|
-
|
|
35
|
-
Agent prompts are literal by default. Set `expandPrompt: true` on an `agent` step only when the prompt should be expanded by Bash at harness runtime, for example to insert values exported by earlier `vars` steps:
|
|
36
|
-
|
|
37
|
-
```yaml
|
|
38
|
-
- type: agent
|
|
39
|
-
name: Fix captured issue
|
|
40
|
-
agent: general
|
|
41
|
-
expandPrompt: true
|
|
42
|
-
prompt: |
|
|
43
|
-
Follow issue #$ISSUE_NUMBER.
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
`expandPrompt: true` is a security-sensitive opt-in: Bash also performs command substitution such as `$(...)` and backticks in the prompt body before OpenCode receives it. Keep it disabled for prompts that contain shell examples or untrusted content.
|
|
47
|
-
|
|
48
|
-
Set `dangerouslySkipPermissions: true` on an `agent` step only when the generated harness should pass OpenCode `--dangerously-skip-permissions`. The flag is false by default, accepts the YAML alias `dangerously-skip-permissions`, and auto-approves permissions that are not explicitly denied. Treat it as security-sensitive and avoid it for untrusted workflows.
|
|
49
|
-
|
|
50
|
-
Harness paths are derived from workflow ids. `wf_example` writes `.harness/example.sh`.
|
|
51
|
-
|
|
52
|
-
## Commands
|
|
53
|
-
|
|
54
|
-
```bash
|
|
55
|
-
# Generate every workflow harness
|
|
56
|
-
uvx flowsh-cli .made/workflows.yml
|
|
57
|
-
|
|
58
|
-
# Generate one workflow by id
|
|
59
|
-
uvx flowsh-cli .made/workflows.yml --workflow wf_example
|
|
60
|
-
|
|
61
|
-
# Show planned outputs without writing files
|
|
62
|
-
uvx flowsh-cli .made/workflows.yml --dry-run
|
|
63
|
-
|
|
64
|
-
# Overwrite existing harness files
|
|
65
|
-
uvx flowsh-cli .made/workflows.yml --force
|
|
66
|
-
|
|
67
|
-
# Show version
|
|
68
|
-
uvx flowsh-cli --version
|
|
69
|
-
|
|
70
|
-
# Show the workflow YAML schema
|
|
71
|
-
uvx flowsh-cli --schema
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
You can also run it via `uv run flowsh-cli` if installed locally.
|
|
75
|
-
|
|
76
|
-
## CLI Contract
|
|
77
|
-
|
|
78
|
-
`flowsh-cli` is non-interactive. It never prompts for missing information.
|
|
79
|
-
|
|
80
|
-
Current help output is plain text and deterministic across repeated runs:
|
|
81
|
-
|
|
82
|
-
```text
|
|
83
|
-
Usage: flowsh-cli [OPTIONS] WORKFLOW_YAML
|
|
84
|
-
|
|
85
|
-
Generate reproducible OpenCode Bash harness scripts from MADE workflow YAML.
|
|
86
|
-
|
|
87
|
-
Arguments:
|
|
88
|
-
WORKFLOW_YAML Path to .made/workflows.yml \[required]
|
|
89
|
-
|
|
90
|
-
Options:
|
|
91
|
-
--workflow TEXT Optional workflow id to generate. Defaults to all workflows.
|
|
92
|
-
--dry-run Print planned output paths without writing scripts.
|
|
93
|
-
--force Overwrite existing files. Without this, existing files cause a failure.
|
|
94
|
-
--version Show the flowsh-cli version and exit.
|
|
95
|
-
--schema Show the workflow YAML schema and exit.
|
|
96
|
-
--help Show this message and exit.
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
The CLI pins its help formatter width so this contract does not vary with the
|
|
100
|
-
caller terminal size or `COLUMNS` environment value.
|
|
101
|
-
|
|
102
|
-
Exit codes:
|
|
103
|
-
|
|
104
|
-
| Case | Exit | stdout | stderr |
|
|
105
|
-
|---|---:|---|---|
|
|
106
|
-
| `--help` | `0` | Help text | Empty |
|
|
107
|
-
| `--version` | `0` | `flowsh-cli <version>` | Empty |
|
|
108
|
-
| `--schema` | `0` | Workflow schema as YAML-formatted JSON Schema | Empty |
|
|
109
|
-
| Valid generation | `0` | One `Wrote <path>` line per harness | Empty |
|
|
110
|
-
| Valid `--dry-run` | `0` | One `DRY-RUN would write <path>` line per selected workflow | Empty |
|
|
111
|
-
| Missing required CLI argument | `2` | Empty | Typer usage error |
|
|
112
|
-
| Malformed or unsupported workflow YAML | `1` | Empty | `ERROR: <reason>` |
|
|
113
|
-
| Unknown `--workflow` id | `1` | Empty | `ERROR: No workflow id matched ...` with known workflow ids |
|
|
114
|
-
| Existing harness without `--force` | `1` | Empty | `ERROR: Refusing to overwrite ...` |
|
|
115
|
-
| Output directory/path safety failure | `1` | Empty | `ERROR: <path safety reason>` |
|
|
116
|
-
|
|
117
|
-
Generated harnesses are also non-interactive. `harness.sh --dry-run` exits `0` after logging planned steps to stderr and creating no log directory. A real harness run exits `0` only after every step succeeds. Failed `bash`, `vars`, or `agent` steps return the failing command status, log `Step failed: <step> (exit=<code>)` to stderr, and stop before later steps run. If an `agent` step runs without `opencode` on `PATH`, the harness exits `127` and prints `opencode CLI not found in PATH` to stderr.
|
|
118
|
-
|
|
119
|
-
Generated harnesses are written with owner-only executable permissions and refuse to overwrite existing paths unless `--force` is passed. Multi-workflow generation preflights overwrite conflicts before writing any harness. `--force` replaces regular harness files and harness-file symlinks, but never replaces a directory at a harness file path. The `.harness` output directory must be a real directory, not a symlink or file. Harness dry runs do not create log files or directories. Real harness logs go to `.flowsh/logs` by default with owner-private directory and file permissions. Set `FLOWSH_LOG_DIR` when running a harness to use another local relative log directory; absolute paths, `..` path segments, symlinked path components, and non-directory log paths are refused. Logging setup and write failures fail the harness instead of being silently ignored.
|
|
120
|
-
|
|
121
|
-
Generated `bash` and `vars` bodies run with `bash -euo pipefail`, so command failures stop the workflow instead of being masked by later successful commands. Captured `vars` values are exported for later `bash` steps. `agent` prompt heredocs are quoted by default and unquoted only when `expandPrompt: true` is set. `agent` steps invoke only `opencode run --format json` with optional `--agent <agent>`, `--model <provider/model>`, `--command <command>`, and `--dangerously-skip-permissions` flags before `-- <prompt>`, so dash-prefixed prompts are message content rather than OpenCode flags. Agent steps fail with a clear error if `opencode` is not on `PATH`.
|
|
122
|
-
|
|
123
|
-
## Development
|
|
124
|
-
|
|
125
|
-
```bash
|
|
126
|
-
uv sync
|
|
127
|
-
make install
|
|
128
|
-
make build
|
|
129
|
-
make qa
|
|
130
|
-
make hygiene
|
|
131
|
-
make clean
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
`make install` installs `flowsh-cli` into the user PATH with `uv tool install --force .`.
|
|
135
|
-
`make build` creates reproducible source and wheel distributions under ignored `dist/`.
|
|
136
|
-
|
|
137
|
-
`make qa` runs Ruff, Python compile checks, and pytest with locked dependencies, then builds packages locally and in CI.
|
|
138
|
-
The pytest suite also verifies `python -m flowsh_cli`, `uvx flowsh-cli`, and the direct
|
|
139
|
-
`scripts/workflow_to_harness.py` entrypoint against the same help contract.
|
|
140
|
-
`make hygiene` prints tracked, untracked, and ignored files with
|
|
141
|
-
`git status --short --ignored`; review it before release to confirm only intended
|
|
142
|
-
source changes are present and generated artifacts remain ignored. `make clean`
|
|
143
|
-
removes local caches, build outputs, generated harnesses, and generated logs.
|
|
144
|
-
|
|
145
|
-
There is no TypeScript compiler, template system, DSL explorer, legacy node
|
|
146
|
-
registry, or archived legacy workflow spec in this repository.
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|