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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowsh-cli
-Version: 0.6.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.6.0 → flowsh_cli-0.7.0}/pyproject.toml

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

{flowsh_cli-0.6.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.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "Workflow",

{flowsh_cli-0.6.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]