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

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

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

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

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

{flowsh_cli-0.5.0 → flowsh_cli-0.7.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.5.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "Workflow",

{flowsh_cli-0.5.0 → flowsh_cli-0.7.0}/src/flowsh_cli/cli.py

@@ -11,6 +11,7 @@ from typing import Annotated
 import typer
 
 from flowsh_cli import __version__
+from flowsh_cli.examples import example_yaml, examples_index
 from flowsh_cli.models import Workflow, WorkflowParseError, parse_workflows, workflow_schema_yaml
 from flowsh_cli.render import harness_path, render_harness
 
@@ -71,11 +72,32 @@ def generate(
             is_eager=True,
         ),
     ] = False,
+    examples: Annotated[
+        bool,
+        typer.Option(
+            "--examples",
+            callback=lambda value: print_examples_index(value),
+            help="List available workflow examples and exit.",
+            is_eager=True,
+        ),
+    ] = False,
+    example: Annotated[
+        str | None,
+        typer.Option(
+            "--example",
+            metavar="NAME",
+            callback=lambda value: print_example(value),
+            help="Print a named example workflow YAML to stdout and exit.",
+            is_eager=True,
+        ),
+    ] = None,
 ) -> None:
     """Generate Bash harnesses from workflow YAML."""
 
     _ = version
     _ = schema
+    _ = examples
+    _ = example
 
     try:
         workflows = parse_workflows(workflow_yaml)
@@ -117,6 +139,26 @@ def print_schema(value: bool) -> None:
     raise typer.Exit
 
 
+def print_examples_index(value: bool) -> None:
+    if not value:
+        return
+
+    print(examples_index())
+    raise typer.Exit
+
+
+def print_example(value: str | None) -> None:
+    if value is None:
+        return
+
+    try:
+        print(example_yaml(value), end="")
+    except ValueError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        raise typer.Exit(1) from error
+    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.7.0/src/flowsh_cli/examples.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+EXAMPLES: dict[str, tuple[str, str, str]] = {
+    # name -> (short_description, step_types, yaml)
+    "simple": (
+        "Vars + sequential bash steps",
+        "vars, bash",
+        """\
+workflows:
+  - id: wf_simple
+    name: Simple example — vars and bash
+
+    steps:
+      - type: vars
+        name: Capture date
+        values:
+          TODAY: date -u +%F       # shell command; stdout becomes the variable
+
+      - type: bash
+        name: Greet
+        run: echo "Hello, today is $TODAY"
+
+      - type: bash
+        name: Done
+        run: echo "Workflow complete"
+""",
+    ),
+    "medium": (
+        "Params + vars + bash + agent with prompt expansion",
+        "vars, bash, agent",
+        """\
+workflows:
+  - id: wf_medium
+    name: Medium example — params, vars, agent
+    params:
+      - name: TOPIC
+        description: Subject to summarise
+        required: true
+    steps:
+      - type: vars
+        values:
+          TODAY: date -u +%F
+      - type: bash
+        run: 'echo "Running on $TODAY for topic: $TOPIC"'
+      - type: agent
+        expandPrompt: true
+        prompt: |
+          Today is ${TODAY}. Write a one-paragraph summary about ${TOPIC}.
+""",
+    ),
+    "sophisticated": (
+        "Params + vars + bash + agent + for + parallel + file handoff",
+        "vars, bash, agent, for, parallel",
+        """\
+workflows:
+  - id: wf_sophisticated
+    name: Sophisticated example — for, parallel, file handoff
+    params:
+      - name: ITEMS
+        description: Newline-delimited list of items to process
+        required: true
+    steps:
+      - type: vars
+        values:
+          OUTFILE: mktemp
+      - type: parallel
+        steps:
+          - type: bash
+            run: echo "worker A started"
+          - type: bash
+            run: echo "worker B started"
+      - type: for
+        in: ITEMS
+        item: ITEM
+        steps:
+          - type: bash
+            run: echo "$ITEM" >> "$OUTFILE"
+      - type: agent
+        expandPrompt: true
+        prompt: |
+          The file ${OUTFILE} contains one processed item per line.
+          Summarise the results.
+""",
+    ),
+}
+
+
+def examples_index() -> str:
+    lines = ["Available examples (use --example <name> to print runnable YAML):\n"]
+    for name, (desc, step_types, _) in EXAMPLES.items():
+        lines.append(f"  {name:<14}{desc}")
+        lines.append(f"  {'':14}Step types: {step_types}\n")
+    return "\n".join(lines)
+
+
+def example_yaml(name: str) -> str:
+    if name not in EXAMPLES:
+        known = ", ".join(EXAMPLES)
+        raise ValueError(f"unknown example {name!r}. Available: {known}")
+    return EXAMPLES[name][2]

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

@@ -154,7 +154,33 @@ class VarsStep(BaseStep):
         return value
 
 
-Step = Annotated[VarsStep | BashStep | AgentStep, Field(discriminator="type")]
+class ForStep(BaseStep):
+    type: Literal["for"]
+    in_: str = Field(..., validation_alias="in")
+    item: str = Field(...)
+    steps: list[Step] = Field(min_length=1)
+
+    @field_validator("in_", "item")
+    @classmethod
+    def validate_var_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 ParallelStep(BaseStep):
+    type: Literal["parallel"]
+    steps: list[Step] = Field(min_length=1)
+
+
+Step = Annotated[
+    VarsStep | BashStep | AgentStep | ForStep | ParallelStep,
+    Field(discriminator="type"),
+]
+
+
+ForStep.model_rebuild()
+ParallelStep.model_rebuild()
 
 
 class WorkflowParam(StrictModel):

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

@@ -3,7 +3,16 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
-from flowsh_cli.models import AgentStep, BashStep, Step, VarsStep, Workflow, WorkflowParam
+from flowsh_cli.models import (
+    AgentStep,
+    BashStep,
+    ForStep,
+    ParallelStep,
+    Step,
+    VarsStep,
+    Workflow,
+    WorkflowParam,
+)
 
 
 def harness_path(workflow: Workflow) -> Path:
@@ -221,8 +230,64 @@ def render_harness(workflow: Workflow) -> str:
 def render_step(index: int, step: Step, used_function_names: set[str] | None = None) -> list[str]:
     function_name = step_function_name(index, step.name, used_function_names)
     title = step.name or default_step_title(index, step)
-    lines = [section(f"Step {index} ({step.type}): {title}"), f"{function_name}() {{"]
 
+    prefix_lines: list[str] = []
+
+    if isinstance(step, ForStep):
+        inner_fns: list[str] = []
+        for i, inner_step in enumerate(step.steps, start=1):
+            inner_fn = _for_inner_function_name(index, i, inner_step, used_function_names)
+            inner_fns.append(inner_fn)
+            inner_title = inner_step.name or default_step_title(i, inner_step)
+            prefix_lines.append(section(f"For-inner step ({inner_step.type}): {inner_title}"))
+            prefix_lines.append(f"{inner_fn}() {{")
+            prefix_lines.extend(_render_step_body(inner_step))
+            prefix_lines.append("}")
+            prefix_lines.append("")
+
+        body_lines = [
+            f"  while IFS= read -r {step.item}; do",
+            f"    export {step.item}",
+            *[f"    run_step {fn}" for fn in inner_fns],
+            f'  done <<< "${{{step.in_}}}"',
+        ]
+    elif isinstance(step, ParallelStep):
+        child_fns: list[str] = []
+        for i, child in enumerate(step.steps, start=1):
+            child_title = child.name or default_step_title(i, child)
+            child_fn = step_function_name(i, child.name, used_function_names)
+            child_fns.append(child_fn)
+            prefix_lines.append(section(f"Parallel child {i} ({child.type}): {child_title}"))
+            prefix_lines.append(f"{child_fn}() {{")
+            prefix_lines.extend(_render_step_body(child))
+            prefix_lines.append("}")
+            prefix_lines.append("")
+
+        body_lines = ["  local status=0"]
+        for child_fn in child_fns:
+            body_lines.append(f'  "{child_fn}" &')
+            body_lines.append(f"  local pid_{child_fn}=$!")
+        for child_fn in child_fns:
+            body_lines.append(f'  wait "$pid_{child_fn}" || status=$?')
+        body_lines.append('  return "$status"')
+    else:
+        body_lines = _render_step_body(step)
+
+    runner = "run_stateful_step" if isinstance(step, (VarsStep, ForStep)) else "run_step"
+    outer_lines = [
+        section(f"Step {index} ({step.type}): {title}"),
+        f"{function_name}() {{",
+        *body_lines,
+        "}",
+        f"{runner} {function_name}",
+        "",
+    ]
+    return prefix_lines + outer_lines
+
+
+def _render_step_body(step: Step) -> list[str]:
+    """Return indented body lines for a step function (no wrapper, no run_step call)."""
+    lines: list[str] = []
     if isinstance(step, VarsStep):
         lines.append("  local status=0")
         for name, command in step.values.items():
@@ -269,7 +334,6 @@ def render_step(index: int, step: Step, used_function_names: set[str] | None = N
             for var in seen:
                 lines.append(f'  _p=\'${{{var}}}\'; prompt="${{prompt//"$_p"/"${var}"}}"')
                 lines.append(f'  _p=\'${var}\'; prompt="${{prompt//"$_p"/"${var}"}}"')
-
         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 '')}")
@@ -278,14 +342,34 @@ def render_step(index: int, step: Step, used_function_names: set[str] | None = N
         lines.append(
             '  run_agent "$prompt" "$agent" "$model" "$command" "$dangerously_skip_permissions"'
         )
+    elif isinstance(step, ForStep):
+        raise AssertionError("nested for steps are not supported")
     else:
         raise AssertionError(f"Unsupported step type: {step}")
-
-    runner = "run_stateful_step" if isinstance(step, VarsStep) else "run_step"
-    lines.extend(["}", f"{runner} {function_name}", ""])
     return lines
 
 
+def _for_inner_function_name(
+    outer_index: int,
+    inner_index: int,
+    step: Step,
+    used_function_names: set[str] | None,
+) -> str:
+    source = step.name or f"step_{inner_index}"
+    slug = re.sub(r"[^A-Za-z0-9_]+", "_", source).strip("_").lower()
+    if not slug or slug[0].isdigit():
+        slug = f"step_{slug}" if slug else f"step_{inner_index}"
+    base = f"for_{outer_index}_{slug}"
+    fn = base
+    suffix = 2
+    while used_function_names is not None and fn in used_function_names:
+        fn = f"{base}_{suffix}"
+        suffix += 1
+    if used_function_names is not None:
+        used_function_names.add(fn)
+    return fn
+
+
 def default_step_title(index: int, step: Step) -> str:
     if isinstance(step, VarsStep):
         return ", ".join(step.values.keys())
@@ -293,6 +377,10 @@ def default_step_title(index: int, step: Step) -> str:
         return truncate_one_line(step.run)
     if isinstance(step, AgentStep):
         return truncate_one_line(step.prompt)
+    if isinstance(step, ForStep):
+        return f"for {step.item} in {step.in_}"
+    if isinstance(step, ParallelStep):
+        return f"parallel ({len(step.steps)} steps)"
     return f"step {index}"