feat: expose workflow schema

Author: Tom Brandenburg

README.md

@@ -62,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.
@@ -85,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.
 ```
 
@@ -97,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 |

pyproject.toml

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

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.2"
+__version__ = "0.3.0"
 
 __all__ = [
     "Workflow",

src/flowsh_cli/cli.py

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

src/flowsh_cli/models.py

@@ -176,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):

tests/test_workflow_to_harness.py

@@ -24,6 +24,7 @@
   --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.
 """
 
@@ -469,6 +470,17 @@ def test_cli_exposes_version_without_workflow_argument() -> None:
     assert result.output.strip().startswith("flowsh-cli ")
 
 
+def test_cli_exposes_schema_without_workflow_argument() -> None:
+    result = runner.invoke(app, ["--schema"])
+
+    assert result.exit_code == 0, result.output
+    assert result.stderr == ""
+    assert "title: WorkflowFile" in result.output
+    assert "const: vars" in result.output
+    assert "const: bash" in result.output
+    assert "const: agent" in result.output
+
+
 def test_cli_reports_missing_required_workflow_argument() -> None:
     result = subprocess.run(
         [sys.executable, "-m", "flowsh_cli"],
@@ -934,6 +946,7 @@ def test_uv_console_entrypoint_help_matches_contract() -> None:
     assert "--dry-run" in result.stdout
     assert "--force" in result.stdout
     assert "--version" in result.stdout
+    assert "--schema" in result.stdout
 
 
 def test_direct_script_entrypoint_help_matches_contract() -> None: