flowsh-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{flowsh_cli-0.2.1 → flowsh_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowsh-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Generate Bash harness scripts from workflow YAML files.
 License-Expression: MIT
 Classifier: Programming Language :: Python :: 3.11
@@ -46,6 +46,19 @@ 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 `-`.
 
+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.
+
 Harness paths are derived from workflow ids. `wf_example` writes `.harness/example.sh`.
 
 ## Commands
@@ -65,6 +78,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 +104,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 +117,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 +130,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 -- <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`.
 
 ## Development
 

{flowsh_cli-0.2.1 → flowsh_cli-0.3.0}/README.md

@@ -30,6 +30,19 @@ 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 `-`.
 
+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.
+
 Harness paths are derived from workflow ids. `wf_example` writes `.harness/example.sh`.
 
 ## Commands
@@ -49,6 +62,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 +88,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 +101,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 +114,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 -- <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`.
 
 ## Development
 

{flowsh_cli-0.2.1 → flowsh_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "flowsh-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "Generate Bash harness scripts from workflow YAML files."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -39,7 +39,6 @@ testpaths = ["tests"]
 [tool.ruff]
 line-length = 100
 target-version = "py311"
-exclude = ["scripts/"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM"]

{flowsh_cli-0.2.1 → flowsh_cli-0.3.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.1"
+__version__ = "0.3.0"
 
 __all__ = [
     "Workflow",

{flowsh_cli-0.2.1 → flowsh_cli-0.3.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.1 → flowsh_cli-0.3.0}/src/flowsh_cli/models.py

@@ -67,6 +67,7 @@ class AgentStep(BaseStep):
     type: Literal["agent"]
     prompt: str
     agent: str | None = None
+    expandPrompt: bool = False
 
     @field_validator("prompt", "agent")
     @classmethod
@@ -175,6 +176,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.1 → flowsh_cli-0.3.0}/src/flowsh_cli/render.py

@@ -245,10 +245,11 @@ 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,
                 "  )",