feat: add --examples and --example flags (#23) (#30)

New users had no built-in way to discover working workflow examples or
bootstrap a starter file. Add two flags following the existing --schema
/ --version eager-callback pattern.

Changes:
- Add src/flowsh_cli/examples.py: single source of truth for three
  example tiers (simple, medium, sophisticated) with helpers
  examples_index() and example_yaml()
- Add --examples (bool) to cli.py: prints the index and exits
- Add --example NAME (str) to cli.py: prints the named YAML and exits,
  exits 1 with a clear error on unknown names
- Update EXPECTED_HELP constant and add 5 new tests covering listing,
  printing, parse validation, dry-run, and unknown-name error

Fixes #23

Co-authored-by: Tom Brandenburg <t_bh@gmx.de>

Author: tbrandenburg

src/flowsh_cli/cli.py

@@ -11,6 +11,7 @@
 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]
 

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]

tests/test_workflow_to_harness.py

@@ -34,6 +34,8 @@
   --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.
+  --examples       List available workflow examples and exit.
+  --example NAME   Print a named example workflow YAML to stdout and exit.
   --help           Show this message and exit.
 """
 
@@ -2615,3 +2617,59 @@ def test_render_harness_parallel_coexists_with_sequential_steps() -> None:
     # Children not individually called at top level
     assert "run_step step_build" not in script
     assert "run_step step_test" not in script
+
+
+# ---------------------------------------------------------------------------
+# --examples / --example tests (issue #23)
+# ---------------------------------------------------------------------------
+
+
+def test_cli_lists_examples_without_workflow_argument() -> None:
+    result = runner.invoke(app, ["--examples"])
+
+    assert result.exit_code == 0, result.output
+    assert "simple" in result.output
+    assert "medium" in result.output
+    assert "sophisticated" in result.output
+    assert "vars, bash" in result.output
+
+
+def test_cli_prints_named_example_yaml_simple() -> None:
+    result = runner.invoke(app, ["--example", "simple"])
+
+    assert result.exit_code == 0, result.output
+    assert "wf_simple" in result.output
+    assert result.output.startswith("workflows:")
+
+
+def test_cli_named_example_is_valid_workflow(tmp_path: Path) -> None:
+    result = runner.invoke(app, ["--example", "simple"])
+    assert result.exit_code == 0
+
+    workflow_file = tmp_path / "simple.yml"
+    workflow_file.write_text(result.output, encoding="utf-8")
+
+    workflows = parse_workflows(workflow_file)
+    assert len(workflows) == 1
+    assert workflows[0].id == "wf_simple"
+
+
+def test_cli_named_example_dry_run(tmp_path: Path) -> None:
+    for name in ("simple", "medium", "sophisticated"):
+        result = runner.invoke(app, ["--example", name])
+        assert result.exit_code == 0, f"--example {name} failed: {result.output}"
+
+        workflow_file = tmp_path / f"{name}.yml"
+        workflow_file.write_text(result.output, encoding="utf-8")
+
+        dry = runner.invoke(app, [str(workflow_file), "--dry-run"])
+        assert dry.exit_code == 0, f"dry-run for {name} failed: {dry.output}"
+
+
+def test_cli_rejects_unknown_example_name() -> None:
+    result = runner.invoke(app, ["--example", "typo"])
+
+    assert result.exit_code == 1
+    combined = result.output + (result.stderr or "")
+    assert "unknown example" in combined
+    assert "simple" in combined