flowsh-cli 0.7.0__tar.gz → 0.7.1__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.
Files changed (11) hide show
  1. flowsh_cli-0.7.1/PKG-INFO +140 -0
  2. flowsh_cli-0.7.1/README.md +124 -0
  3. {flowsh_cli-0.7.0 → flowsh_cli-0.7.1}/pyproject.toml +1 -1
  4. {flowsh_cli-0.7.0 → flowsh_cli-0.7.1}/src/flowsh_cli/__init__.py +1 -1
  5. flowsh_cli-0.7.0/PKG-INFO +0 -162
  6. flowsh_cli-0.7.0/README.md +0 -146
  7. {flowsh_cli-0.7.0 → flowsh_cli-0.7.1}/src/flowsh_cli/__main__.py +0 -0
  8. {flowsh_cli-0.7.0 → flowsh_cli-0.7.1}/src/flowsh_cli/cli.py +0 -0
  9. {flowsh_cli-0.7.0 → flowsh_cli-0.7.1}/src/flowsh_cli/examples.py +0 -0
  10. {flowsh_cli-0.7.0 → flowsh_cli-0.7.1}/src/flowsh_cli/models.py +0 -0
  11. {flowsh_cli-0.7.0 → flowsh_cli-0.7.1}/src/flowsh_cli/render.py +0 -0
flowsh_cli-0.7.1/PKG-INFO ADDED
@@ -0,0 +1,140 @@
1
+ Metadata-Version: 2.4
2
+ Name: flowsh-cli
3
+ Version: 0.7.1
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 .made/workflows.yml
27
+ ```
28
+
29
+ That reads `.made/workflows.yml` and writes harnesses under `.harness/`.
30
+
31
+ Useful flags:
32
+
33
+ ```bash
34
+ uvx flowsh-cli .made/workflows.yml --dry-run
35
+ uvx flowsh-cli .made/workflows.yml --workflow wf_example
36
+ uvx flowsh-cli .made/workflows.yml --force
37
+ uvx flowsh-cli .made/workflows.yml --schema
38
+ uvx flowsh-cli --examples
39
+ uvx flowsh-cli --example simple
40
+ ```
41
+
42
+ You can also run it locally with `uv run flowsh-cli`.
43
+
44
+ ## Workflow Shape
45
+
46
+ The input file is a single mapping with a `workflows` list:
47
+
48
+ ```yaml
49
+ workflows:
50
+ - id: wf_example
51
+ name: Example
52
+ params:
53
+ - name: ISSUE_NUMBER
54
+ description: Issue to inspect
55
+ required: true
56
+ steps:
57
+ - type: vars
58
+ values:
59
+ TODAY: date -u +%F
60
+ - type: bash
61
+ run: printf 'today=%s\n' "$TODAY"
62
+ - type: agent
63
+ agent: general
64
+ model: openai/gpt-5
65
+ command: review
66
+ expandPrompt: true
67
+ prompt: |
68
+ Review issue ${ISSUE_NUMBER} and summarize the repository state.
69
+ - type: parallel
70
+ steps:
71
+ - type: bash
72
+ run: echo "worker A"
73
+ - type: bash
74
+ run: echo "worker B"
75
+ - type: for
76
+ in: ITEMS
77
+ item: ITEM
78
+ steps:
79
+ - type: bash
80
+ run: echo "$ITEM"
81
+ ```
82
+
83
+ Harness paths are derived from workflow ids. `wf_example` becomes `.harness/example.sh`.
84
+
85
+ ## Step Types
86
+
87
+ | Type | Purpose | Notes |
88
+ |---|---|---|
89
+ | `vars` | Capture command output into exported shell variables | Variable names must be uppercase shell identifiers. |
90
+ | `bash` | Run shell commands | Runs with `bash -euo pipefail`. |
91
+ | `agent` | Call OpenCode | Supports `agent`, `model`, `command`, `expandPrompt`, and `dangerouslySkipPermissions`. |
92
+ | `for` | Iterate over newline-delimited input | Flat iteration only; nested `for` steps are not supported. |
93
+ | `parallel` | Run child steps concurrently | Children run as separate branches and the parent waits for all of them. |
94
+
95
+ ## Agent Behavior
96
+
97
+ `agent` prompts are literal by default. Use `expandPrompt: true` only when you want `$VAR` or `${VAR}` tokens from earlier `vars` steps substituted at runtime.
98
+
99
+ `expandPrompt: true` does plain text replacement only. It does not evaluate shell expressions like `$(...)`, backticks, or globs.
100
+
101
+ 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.
102
+
103
+ ## Validation And Safety
104
+
105
+ The parser is strict:
106
+
107
+ - workflow YAML must be UTF-8, non-empty, and under 1 MiB
108
+ - the root must be a mapping with a `workflows` key
109
+ - duplicate mapping keys and YAML aliases are rejected
110
+ - workflow ids must match `wf_[A-Za-z0-9_-]+`
111
+ - workflow and step names must be non-empty single-line labels
112
+ - unsafe control characters are rejected in executable fields
113
+ - `agent` names may contain only letters, digits, `_`, and `-`
114
+
115
+ Generated harnesses are non-interactive, owner-executable, and refuse to overwrite existing outputs unless `--force` is set.
116
+
117
+ Logs go to `.flowsh/logs` by default. Set `FLOWSH_LOG_DIR` to use another relative log directory.
118
+
119
+ ## Development
120
+
121
+ ```bash
122
+ uv sync
123
+ make install
124
+ make qa
125
+ make clean
126
+ ```
127
+
128
+ `make qa` runs linting, tests, and a local build.
129
+
130
+ ## Release
131
+
132
+ ```bash
133
+ make bump-patch
134
+ ```
135
+
136
+ That bumps the patch version, runs QA, and publishes the package.
137
+
138
+ ## Limits
139
+
140
+ 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.
flowsh_cli-0.7.1/README.md ADDED
@@ -0,0 +1,124 @@
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 .made/workflows.yml
11
+ ```
12
+
13
+ That reads `.made/workflows.yml` and writes harnesses under `.harness/`.
14
+
15
+ Useful flags:
16
+
17
+ ```bash
18
+ uvx flowsh-cli .made/workflows.yml --dry-run
19
+ uvx flowsh-cli .made/workflows.yml --workflow wf_example
20
+ uvx flowsh-cli .made/workflows.yml --force
21
+ uvx flowsh-cli .made/workflows.yml --schema
22
+ uvx flowsh-cli --examples
23
+ uvx flowsh-cli --example simple
24
+ ```
25
+
26
+ You can also run it locally with `uv run flowsh-cli`.
27
+
28
+ ## Workflow Shape
29
+
30
+ The input file is a single mapping with a `workflows` list:
31
+
32
+ ```yaml
33
+ workflows:
34
+ - id: wf_example
35
+ name: Example
36
+ params:
37
+ - name: ISSUE_NUMBER
38
+ description: Issue to inspect
39
+ required: true
40
+ steps:
41
+ - type: vars
42
+ values:
43
+ TODAY: date -u +%F
44
+ - type: bash
45
+ run: printf 'today=%s\n' "$TODAY"
46
+ - type: agent
47
+ agent: general
48
+ model: openai/gpt-5
49
+ command: review
50
+ expandPrompt: true
51
+ prompt: |
52
+ Review issue ${ISSUE_NUMBER} and summarize the repository state.
53
+ - type: parallel
54
+ steps:
55
+ - type: bash
56
+ run: echo "worker A"
57
+ - type: bash
58
+ run: echo "worker B"
59
+ - type: for
60
+ in: ITEMS
61
+ item: ITEM
62
+ steps:
63
+ - type: bash
64
+ run: echo "$ITEM"
65
+ ```
66
+
67
+ Harness paths are derived from workflow ids. `wf_example` becomes `.harness/example.sh`.
68
+
69
+ ## Step Types
70
+
71
+ | Type | Purpose | Notes |
72
+ |---|---|---|
73
+ | `vars` | Capture command output into exported shell variables | Variable names must be uppercase shell identifiers. |
74
+ | `bash` | Run shell commands | Runs with `bash -euo pipefail`. |
75
+ | `agent` | Call OpenCode | Supports `agent`, `model`, `command`, `expandPrompt`, and `dangerouslySkipPermissions`. |
76
+ | `for` | Iterate over newline-delimited input | Flat iteration only; nested `for` steps are not supported. |
77
+ | `parallel` | Run child steps concurrently | Children run as separate branches and the parent waits for all of them. |
78
+
79
+ ## Agent Behavior
80
+
81
+ `agent` prompts are literal by default. Use `expandPrompt: true` only when you want `$VAR` or `${VAR}` tokens from earlier `vars` steps substituted at runtime.
82
+
83
+ `expandPrompt: true` does plain text replacement only. It does not evaluate shell expressions like `$(...)`, backticks, or globs.
84
+
85
+ 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.
86
+
87
+ ## Validation And Safety
88
+
89
+ The parser is strict:
90
+
91
+ - workflow YAML must be UTF-8, non-empty, and under 1 MiB
92
+ - the root must be a mapping with a `workflows` key
93
+ - duplicate mapping keys and YAML aliases are rejected
94
+ - workflow ids must match `wf_[A-Za-z0-9_-]+`
95
+ - workflow and step names must be non-empty single-line labels
96
+ - unsafe control characters are rejected in executable fields
97
+ - `agent` names may contain only letters, digits, `_`, and `-`
98
+
99
+ Generated harnesses are non-interactive, owner-executable, and refuse to overwrite existing outputs unless `--force` is set.
100
+
101
+ Logs go to `.flowsh/logs` by default. Set `FLOWSH_LOG_DIR` to use another relative log directory.
102
+
103
+ ## Development
104
+
105
+ ```bash
106
+ uv sync
107
+ make install
108
+ make qa
109
+ make clean
110
+ ```
111
+
112
+ `make qa` runs linting, tests, and a local build.
113
+
114
+ ## Release
115
+
116
+ ```bash
117
+ make bump-patch
118
+ ```
119
+
120
+ That bumps the patch version, runs QA, and publishes the package.
121
+
122
+ ## Limits
123
+
124
+ 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.
{flowsh_cli-0.7.0 → flowsh_cli-0.7.1}/pyproject.toml RENAMED
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "flowsh-cli"
7
- version = "0.7.0"
7
+ version = "0.7.1"
8
8
  description = "Generate Bash harness scripts from workflow YAML files."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
{flowsh_cli-0.7.0 → flowsh_cli-0.7.1}/src/flowsh_cli/__init__.py RENAMED
@@ -3,7 +3,7 @@
3
3
  from flowsh_cli.models import Workflow, WorkflowParseError, parse_workflows
4
4
  from flowsh_cli.render import harness_path, render_harness
5
5
 
6
- __version__ = "0.7.0"
6
+ __version__ = "0.7.1"
7
7
 
8
8
  __all__ = [
9
9
  "Workflow",
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.