flowsh-cli 0.2.2__tar.gz → 0.4.0__tar.gz

{flowsh_cli-0.2.2 → flowsh_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowsh-cli
-Version: 0.2.2
+Version: 0.4.0
 Summary: Generate Bash harness scripts from workflow YAML files.
 License-Expression: MIT
 Classifier: Programming Language :: Python :: 3.11
@@ -38,13 +38,30 @@ workflows:
       - type: agent
         name: Ask OpenCode
         agent: general
+        model: openai/gpt-5
+        command: review
         prompt: |
           Summarize the current repository state.
 ```
 
 Supported step types are only `vars`, `bash`, and `agent`.
 
-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 `-`.
+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 `--`.
+
+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:
+
+```yaml
+- type: agent
+  name: Fix captured issue
+  agent: general
+  expandPrompt: true
+  prompt: |
+    Follow issue #$ISSUE_NUMBER.
+```
+
+`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.
+
+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.
 
 Harness paths are derived from workflow ids. `wf_example` writes `.harness/example.sh`.
 
@@ -65,6 +82,9 @@ uvx flowsh-cli .made/workflows.yml --force
 
 # Show version
 uvx flowsh-cli --version
+
+# Show the workflow YAML schema
+uvx flowsh-cli --schema
 ```
 
 You can also run it via `uv run flowsh-cli` if installed locally.
@@ -88,6 +108,7 @@ Options:
   --dry-run        Print planned output paths without writing scripts.
   --force          Overwrite existing files. Without this, existing files cause a failure.
   --version        Show the flowsh-cli version and exit.
+  --schema         Show the workflow YAML schema and exit.
   --help           Show this message and exit.
 ```
 
@@ -100,6 +121,7 @@ Exit codes:
 |---|---:|---|---|
 | `--help` | `0` | Help text | Empty |
 | `--version` | `0` | `flowsh-cli <version>` | Empty |
+| `--schema` | `0` | Workflow schema as YAML-formatted JSON Schema | Empty |
 | Valid generation | `0` | One `Wrote <path>` line per harness | Empty |
 | Valid `--dry-run` | `0` | One `DRY-RUN would write <path>` line per selected workflow | Empty |
 | Missing required CLI argument | `2` | Empty | Typer usage error |
@@ -112,7 +134,7 @@ Generated harnesses are also non-interactive. `harness.sh --dry-run` exits `0` a
 
 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.
 
-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` steps invoke only `opencode run --format json -- <prompt>` with optional `--agent <agent>` before `--`, so dash-prefixed prompts are message content rather than OpenCode flags. Agent steps fail with a clear error if `opencode` is not on `PATH`.
+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`.
 
 ## Development
 

{flowsh_cli-0.2.2 → flowsh_cli-0.4.0}/README.md

@@ -22,13 +22,30 @@ workflows:
       - type: agent
         name: Ask OpenCode
         agent: general
+        model: openai/gpt-5
+        command: review
         prompt: |
           Summarize the current repository state.
 ```
 
 Supported step types are only `vars`, `bash`, and `agent`.
 
-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 `-`.
+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 `--`.
+
+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:
+
+```yaml
+- type: agent
+  name: Fix captured issue
+  agent: general
+  expandPrompt: true
+  prompt: |
+    Follow issue #$ISSUE_NUMBER.
+```
+
+`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.
+
+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.
 
 Harness paths are derived from workflow ids. `wf_example` writes `.harness/example.sh`.
 
@@ -49,6 +66,9 @@ uvx flowsh-cli .made/workflows.yml --force
 
 # Show version
 uvx flowsh-cli --version
+
+# Show the workflow YAML schema
+uvx flowsh-cli --schema
 ```
 
 You can also run it via `uv run flowsh-cli` if installed locally.
@@ -72,6 +92,7 @@ Options:
   --dry-run        Print planned output paths without writing scripts.
   --force          Overwrite existing files. Without this, existing files cause a failure.
   --version        Show the flowsh-cli version and exit.
+  --schema         Show the workflow YAML schema and exit.
   --help           Show this message and exit.
 ```
 
@@ -84,6 +105,7 @@ Exit codes:
 |---|---:|---|---|
 | `--help` | `0` | Help text | Empty |
 | `--version` | `0` | `flowsh-cli <version>` | Empty |
+| `--schema` | `0` | Workflow schema as YAML-formatted JSON Schema | Empty |
 | Valid generation | `0` | One `Wrote <path>` line per harness | Empty |
 | Valid `--dry-run` | `0` | One `DRY-RUN would write <path>` line per selected workflow | Empty |
 | Missing required CLI argument | `2` | Empty | Typer usage error |
@@ -96,7 +118,7 @@ Generated harnesses are also non-interactive. `harness.sh --dry-run` exits `0` a
 
 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.
 
-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` steps invoke only `opencode run --format json -- <prompt>` with optional `--agent <agent>` before `--`, so dash-prefixed prompts are message content rather than OpenCode flags. Agent steps fail with a clear error if `opencode` is not on `PATH`.
+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`.
 
 ## Development
 

{flowsh_cli-0.2.2 → flowsh_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "flowsh-cli"
-version = "0.2.2"
+version = "0.4.0"
 description = "Generate Bash harness scripts from workflow YAML files."
 readme = "README.md"
 requires-python = ">=3.11"

{flowsh_cli-0.2.2 → flowsh_cli-0.4.0}/src/flowsh_cli/__init__.py

@@ -3,7 +3,7 @@
 from flowsh_cli.models import Workflow, WorkflowParseError, parse_workflows
 from flowsh_cli.render import harness_path, render_harness
 
-__version__ = "0.2.2"
+__version__ = "0.4.0"
 
 __all__ = [
     "Workflow",

{flowsh_cli-0.2.2 → flowsh_cli-0.4.0}/src/flowsh_cli/cli.py

@@ -11,7 +11,7 @@ from typing import Annotated
 import typer
 
 from flowsh_cli import __version__
-from flowsh_cli.models import Workflow, WorkflowParseError, parse_workflows
+from flowsh_cli.models import Workflow, WorkflowParseError, parse_workflows, workflow_schema_yaml
 from flowsh_cli.render import harness_path, render_harness
 
 app = typer.Typer(
@@ -62,10 +62,20 @@ def generate(
             is_eager=True,
         ),
     ] = False,
+    schema: Annotated[
+        bool,
+        typer.Option(
+            "--schema",
+            callback=lambda value: print_schema(value),
+            help="Show the workflow YAML schema and exit.",
+            is_eager=True,
+        ),
+    ] = False,
 ) -> None:
     """Generate Bash harnesses from workflow YAML."""
 
     _ = version
+    _ = schema
 
     try:
         workflows = parse_workflows(workflow_yaml)
@@ -99,6 +109,14 @@ def print_version(value: bool) -> None:
     raise typer.Exit
 
 
+def print_schema(value: bool) -> None:
+    if not value:
+        return
+
+    print(workflow_schema_yaml(), end="")
+    raise typer.Exit
+
+
 def write_harnesses(workflows: list[Workflow], *, dry_run: bool, force: bool) -> None:
     output_paths = [(workflow, harness_path(workflow)) for workflow in workflows]
 

{flowsh_cli-0.2.2 → flowsh_cli-0.4.0}/src/flowsh_cli/models.py

@@ -7,7 +7,15 @@ from pathlib import Path
 from typing import Annotated, Literal
 
 import yaml
-from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+from pydantic import (
+    AliasChoices,
+    BaseModel,
+    ConfigDict,
+    Field,
+    ValidationError,
+    field_validator,
+    model_validator,
+)
 
 MAX_WORKFLOW_YAML_BYTES = 1_048_576
 
@@ -67,8 +75,31 @@ class AgentStep(BaseStep):
     type: Literal["agent"]
     prompt: str
     agent: str | None = None
+    model: str | None = None
+    command: str | None = None
+    dangerouslySkipPermissions: bool = Field(
+        default=False,
+        validation_alias=AliasChoices(
+            "dangerouslySkipPermissions",
+            "dangerously-skip-permissions",
+        ),
+    )
+    expandPrompt: bool = False
+
+    @model_validator(mode="before")
+    @classmethod
+    def reject_ambiguous_dangerous_aliases(cls, data: object) -> object:
+        if (
+            isinstance(data, Mapping)
+            and "dangerouslySkipPermissions" in data
+            and "dangerously-skip-permissions" in data
+        ):
+            raise ValueError(
+                "dangerouslySkipPermissions and dangerously-skip-permissions must not both be set"
+            )
+        return data
 
-    @field_validator("prompt", "agent")
+    @field_validator("prompt", "agent", "model", "command")
     @classmethod
     def validate_strings(cls, value: str | None) -> str | None:
         if value is not None and value.strip() == "":
@@ -175,6 +206,14 @@ def parse_workflows(path: Path) -> list[Workflow]:
         raise WorkflowParseError(format_validation_error(error)) from error
 
 
+def workflow_schema_yaml() -> str:
+    return yaml.safe_dump(
+        WorkflowFile.model_json_schema(),
+        sort_keys=False,
+        allow_unicode=False,
+    )
+
+
 def format_validation_error(error: ValidationError) -> str:
     messages: list[str] = []
     for item in error.errors(include_url=False, include_input=False, include_context=False):

{flowsh_cli-0.2.2 → flowsh_cli-0.4.0}/src/flowsh_cli/render.py

@@ -174,11 +174,23 @@ def render_harness(workflow: Workflow) -> str:
         "run_agent() {",
         '  local prompt="$1"',
         '  local agent="${2:-}"',
+        '  local model="${3:-}"',
+        '  local command="${4:-}"',
+        '  local dangerously_skip_permissions="${5:-false}"',
         "",
         "  local cmd=(opencode run --format json)",
         '  if [[ -n "$agent" ]]; then',
         '    cmd+=(--agent "$agent")',
         "  fi",
+        '  if [[ -n "$model" ]]; then',
+        '    cmd+=(--model "$model")',
+        "  fi",
+        '  if [[ -n "$command" ]]; then',
+        '    cmd+=(--command "$command")',
+        "  fi",
+        '  if [[ "$dangerously_skip_permissions" == true ]]; then',
+        "    cmd+=(--dangerously-skip-permissions)",
+        "  fi",
         "",
         '  if [[ "$DRY_RUN" == true ]]; then',
         '    log INFO "[DRY-RUN] would run: $(printf \'%q \' "${cmd[@]}") (with prompt)"',
@@ -245,20 +257,24 @@ def render_step(index: int, step: Step, used_function_names: set[str] | None = N
         )
     elif isinstance(step, AgentStep):
         delimiter = heredoc_delimiter("PROMPT", step.prompt)
+        heredoc = f"<<{delimiter}" if step.expandPrompt else f"<<'{delimiter}'"
         lines.extend(
             [
                 "  local prompt",
-                f"  prompt=$(cat <<'{delimiter}'",
+                f"  prompt=$(cat {heredoc}",
                 *step.prompt.splitlines(),
                 delimiter,
                 "  )",
             ]
         )
-        if step.agent:
-            lines.append(f"  local agent={bash_quote(step.agent)}")
-            lines.append('  run_agent "$prompt" "$agent"')
-        else:
-            lines.append('  run_agent "$prompt"')
+        lines.append(f"  local agent={bash_quote(step.agent or '')}")
+        lines.append(f"  local model={bash_quote(step.model or '')}")
+        lines.append(f"  local command={bash_quote(step.command or '')}")
+        dangerous_skip_permissions = "true" if step.dangerouslySkipPermissions else "false"
+        lines.append(f"  local dangerously_skip_permissions={dangerous_skip_permissions}")
+        lines.append(
+            '  run_agent "$prompt" "$agent" "$model" "$command" "$dangerously_skip_permissions"'
+        )
     else:
         raise AssertionError(f"Unsupported step type: {step}")