flowsh-cli 0.4.1__tar.gz → 0.5.0__tar.gz

{flowsh_cli-0.4.1 → flowsh_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowsh-cli
-Version: 0.4.1
+Version: 0.5.0
 Summary: Generate Bash harness scripts from workflow YAML files.
 License-Expression: MIT
 Classifier: Programming Language :: Python :: 3.11

{flowsh_cli-0.4.1 → flowsh_cli-0.5.0}/pyproject.toml

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

{flowsh_cli-0.4.1 → flowsh_cli-0.5.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.4.1"
+__version__ = "0.5.0"
 
 __all__ = [
     "Workflow",

{flowsh_cli-0.4.1 → flowsh_cli-0.5.0}/src/flowsh_cli/models.py

@@ -73,7 +73,14 @@ class BashStep(BaseStep):
 
 class AgentStep(BaseStep):
     type: Literal["agent"]
-    prompt: str
+    prompt: str = Field(
+        description=(
+            "The prompt text sent to the agent. "
+            "May contain markdown, code fences, backticks, $(...), and other shell syntax freely — "
+            "the prompt is never passed through a shell. "
+            "Use expandPrompt: true to substitute ${VAR} / $VAR tokens from vars steps."
+        )
+    )
     agent: str | None = None
     model: str | None = None
     command: str | None = None
@@ -84,7 +91,17 @@ class AgentStep(BaseStep):
             "dangerously-skip-permissions",
         ),
     )
-    expandPrompt: bool = False
+    expandPrompt: bool = Field(
+        default=False,
+        description=(
+            "When true, substitutes ${VAR} and $VAR tokens from vars steps into the prompt "
+            "at runtime using safe plain-text replacement. "
+            "Shell expressions such as $(cmd), `cmd`, $((expr)), and globs are NOT evaluated — "
+            "they pass through to the agent literally. "
+            "Only uppercase variable names matching [A-Z_][A-Z0-9_]* found in the prompt text "
+            "are replaced. All other shell syntax in the prompt is safe to use."
+        ),
+    )
 
     @model_validator(mode="before")
     @classmethod
@@ -140,9 +157,23 @@ class VarsStep(BaseStep):
 Step = Annotated[VarsStep | BashStep | AgentStep, Field(discriminator="type")]
 
 
+class WorkflowParam(StrictModel):
+    name: str
+    description: str | None = None
+    required: bool = False
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, value: str) -> str:
+        if not re.fullmatch(r"[A-Z_][A-Z0-9_]*", value):
+            raise ValueError("must match ^[A-Z_][A-Z0-9_]*$")
+        return value
+
+
 class Workflow(StrictModel):
     id: str
     name: str
+    params: list[WorkflowParam] = []
     steps: list[Step]
 
     @field_validator("id")

{flowsh_cli-0.4.1 → flowsh_cli-0.5.0}/src/flowsh_cli/render.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
-from flowsh_cli.models import AgentStep, BashStep, Step, VarsStep, Workflow
+from flowsh_cli.models import AgentStep, BashStep, Step, VarsStep, Workflow, WorkflowParam
 
 
 def harness_path(workflow: Workflow) -> Path:
@@ -26,13 +26,7 @@ def render_harness(workflow: Workflow) -> str:
         'LOG_BASENAME="flowsh-${WORKFLOW_SLUG}-${LOG_TIMESTAMP}-$$.log"',
         "",
         section("Argument handling"),
-        "DRY_RUN=false",
-        'if [[ $# -eq 1 && "$1" == "--dry-run" ]]; then',
-        "  DRY_RUN=true",
-        "elif [[ $# -gt 0 ]]; then",
-        '  printf "Usage: %s [--dry-run]\\n" "$0" >&2',
-        "  exit 2",
-        "fi",
+        *_render_arg_block(workflow.params),
         "",
         section("refuse_symlink_path() - keep generated logs inside plain relative paths"),
         "refuse_symlink_path() {",
@@ -353,6 +347,69 @@ def bash_quote(value: str) -> str:
     return "'" + value.replace("'", "'\\''") + "'"
 
 
+def _render_arg_block(params: list[WorkflowParam]) -> list[str]:
+    if not params:
+        return [
+            "DRY_RUN=false",
+            'if [[ $# -eq 1 && "$1" == "--dry-run" ]]; then',
+            "  DRY_RUN=true",
+            "elif [[ $# -gt 0 ]]; then",
+            '  printf "Usage: %s [--dry-run]\\n" "$0" >&2',
+            "  exit 2",
+            "fi",
+        ]
+
+    usage_parts: list[str] = ["[--dry-run]"]
+    for p in params:
+        usage_parts.append(f"<{p.name}>" if p.required else f"[{p.name}]")
+    usage_str = " ".join(usage_parts)
+
+    lines: list[str] = [
+        "DRY_RUN=false",
+        "POSITIONAL_ARGS=()",
+        "",
+        "while [[ $# -gt 0 ]]; do",
+        '  case "$1" in',
+        "    --dry-run)",
+        "      DRY_RUN=true",
+        "      shift",
+        "      ;;",
+        "    --*)",
+        '      printf "Unknown option: %s\\n" "$1" >&2',
+        "      exit 2",
+        "      ;;",
+        "    *)",
+        '      POSITIONAL_ARGS+=("$1")',
+        "      shift",
+        "      ;;",
+        "  esac",
+        "done",
+        "",
+    ]
+
+    for idx, param in enumerate(params):
+        lines += [
+            f"if [[ ${{#POSITIONAL_ARGS[@]}} -gt {idx} ]]; then",
+            f'  {param.name}="${{POSITIONAL_ARGS[{idx}]}}"',
+            f"  export {param.name}",
+            "fi",
+        ]
+
+    lines.append("")
+
+    required = [p for p in params if p.required]
+    if required:
+        for param in required:
+            lines += [
+                f'if [[ -z "${{{param.name}:-}}" ]]; then',
+                f'  printf "Usage: %s {usage_str}\\n" "$0" >&2',
+                "  exit 2",
+                "fi",
+            ]
+
+    return lines
+
+
 def section(title: str) -> str:
     safe_title = truncate_one_line(title, limit=120)
     return "\n".join(