flowsh-cli 0.1.0__tar.gz

flowsh_cli-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: flowsh-cli
+Version: 0.1.0
+Summary: Generate Bash harness scripts from MADE workflow YAML files.
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pyyaml>=6,<7
+Requires-Dist: pydantic>=2,<3
+Requires-Dist: typer>=0.20,<0.21
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/tbrandenburg/flowsh
+Project-URL: Source, https://github.com/tbrandenburg/flowsh
+Description-Content-Type: text/markdown
+
+# flowsh
+
+`flowsh` is a small `uv` Python CLI deliberately reduced to one tool:
+
+```bash
+uv run flowsh .made/workflows.yml
+```
+
+It reads MADE workflow YAML and writes executable Bash harness scripts for OpenCode.
+
+## Supported YAML
+
+Only this top-level shape is supported:
+
+```yaml
+workflows:
+  - id: wf_example
+    name: Example
+    steps:
+      - type: vars
+        name: Capture date
+        values:
+          TODAY: date -u +%F
+      - type: bash
+        name: Print date
+        run: |
+          printf 'today=%s\n' "$TODAY"
+      - type: agent
+        name: Ask OpenCode
+        agent: general
+        prompt: |
+          Summarize the current repository state.
+```
+
+Supported step types are only `vars`, `bash`, and `agent`.
+
+The input path must be a regular file no larger than 1 MiB. The input file must be valid UTF-8, non-empty YAML with a mapping root, no duplicate mapping keys, and no YAML aliases. Workflow and step names are single-line labels. Executable fields reject unsafe control bytes while allowing normal newlines and tabs. `vars` keys must be uppercase shell variable names, and `agent` names may contain only letters, digits, `_`, and `-`.
+
+Harness paths are derived from workflow ids. `wf_example` writes `.harness/example.sh`.
+
+## Commands
+
+```bash
+# Generate every workflow harness
+uv run flowsh .made/workflows.yml
+
+# Generate one workflow by id
+uv run flowsh .made/workflows.yml --workflow wf_example
+
+# Show planned outputs without writing files
+uv run flowsh .made/workflows.yml --dry-run
+
+# Overwrite existing harness files
+uv run flowsh .made/workflows.yml --force
+
+# Show version
+uv run flowsh --version
+```
+
+## CLI Contract
+
+`flowsh` is non-interactive. It never prompts for missing information.
+
+Current help output is plain text and deterministic across repeated runs:
+
+```text
+Usage: flowsh [OPTIONS] WORKFLOW_YAML
+
+  Generate reproducible OpenCode Bash harness scripts from MADE workflow YAML.
+
+Arguments:
+  WORKFLOW_YAML  Path to .made/workflows.yml  \[required]
+
+Options:
+  --workflow TEXT  Optional workflow id to generate. Defaults to all workflows.
+  --dry-run        Print planned output paths without writing scripts.
+  --force          Overwrite existing files. Without this, existing files cause a failure.
+  --version        Show the flowsh version and exit.
+  --help           Show this message and exit.
+```
+
+The CLI pins its help formatter width so this contract does not vary with the
+caller terminal size or `COLUMNS` environment value.
+
+Exit codes:
+
+| Case | Exit | stdout | stderr |
+|---|---:|---|---|
+| `--help` | `0` | Help text | Empty |
+| `--version` | `0` | `flowsh <version>` | 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 |
+| Malformed or unsupported workflow YAML | `1` | Empty | `ERROR: <reason>` |
+| Unknown `--workflow` id | `1` | Empty | `ERROR: No workflow id matched ...` with known workflow ids |
+| Existing harness without `--force` | `1` | Empty | `ERROR: Refusing to overwrite ...` |
+| Output directory/path safety failure | `1` | Empty | `ERROR: <path safety reason>` |
+
+Generated harnesses are also non-interactive. `harness.sh --dry-run` exits `0` after logging planned steps to stderr and creating no log directory. A real harness run exits `0` only after every step succeeds. Failed `bash`, `vars`, or `agent` steps return the failing command status, log `Step failed: <step> (exit=<code>)` to stderr, and stop before later steps run. If an `agent` step runs without `opencode` on `PATH`, the harness exits `127` and prints `opencode CLI not found in PATH` to stderr.
+
+Generated harnesses are written with owner-only executable permissions and refuse to overwrite existing paths unless `--force` is passed. Multi-workflow generation preflights overwrite conflicts before writing any harness. `--force` replaces regular harness files and harness-file symlinks, but never replaces a directory at a harness file path. The `.harness` output directory must be a real directory, not a symlink or file. Harness dry runs do not create log files or directories. Real harness logs go to `.flowsh/logs` by default with owner-private directory and file permissions. Set `FLOWSH_LOG_DIR` when running a harness to use another local relative log directory; absolute paths, `..` path segments, symlinked path components, and non-directory log paths are refused. Logging setup and write failures fail the harness instead of being silently ignored.
+
+Generated `bash` and `vars` bodies run with `bash -euo pipefail`, so command failures stop the workflow instead of being masked by later successful commands. Captured `vars` values are exported for later `bash` steps. `agent` steps invoke only `opencode run --format json -- <prompt>` with optional `--agent <agent>` before `--`, so dash-prefixed prompts are message content rather than OpenCode flags. Agent steps fail with a clear error if `opencode` is not on `PATH`.
+
+## Development
+
+```bash
+uv sync
+make install
+make build
+make qa
+make hygiene
+make clean
+```
+
+`make install` installs `flowsh` into the user PATH with `uv tool install --force .`.
+`make build` creates reproducible source and wheel distributions under ignored `dist/`.
+
+`make qa` runs Ruff, Python compile checks, and pytest with locked dependencies, then builds packages locally and in CI.
+The pytest suite also verifies `python -m flowsh`, `uv run flowsh`, and the direct
+`scripts/workflow_to_harness.py` entrypoint against the same help contract.
+`make hygiene` prints tracked, untracked, and ignored files with
+`git status --short --ignored`; review it before release to confirm only intended
+source changes are present and generated artifacts remain ignored. `make clean`
+removes local caches, build outputs, generated harnesses, and generated logs.
+
+There is no TypeScript compiler, template system, DSL explorer, legacy node
+registry, or archived legacy workflow spec in this repository.

flowsh_cli-0.1.0/README.md

@@ -0,0 +1,128 @@
+# flowsh
+
+`flowsh` is a small `uv` Python CLI deliberately reduced to one tool:
+
+```bash
+uv run flowsh .made/workflows.yml
+```
+
+It reads MADE workflow YAML and writes executable Bash harness scripts for OpenCode.
+
+## Supported YAML
+
+Only this top-level shape is supported:
+
+```yaml
+workflows:
+  - id: wf_example
+    name: Example
+    steps:
+      - type: vars
+        name: Capture date
+        values:
+          TODAY: date -u +%F
+      - type: bash
+        name: Print date
+        run: |
+          printf 'today=%s\n' "$TODAY"
+      - type: agent
+        name: Ask OpenCode
+        agent: general
+        prompt: |
+          Summarize the current repository state.
+```
+
+Supported step types are only `vars`, `bash`, and `agent`.
+
+The input path must be a regular file no larger than 1 MiB. The input file must be valid UTF-8, non-empty YAML with a mapping root, no duplicate mapping keys, and no YAML aliases. Workflow and step names are single-line labels. Executable fields reject unsafe control bytes while allowing normal newlines and tabs. `vars` keys must be uppercase shell variable names, and `agent` names may contain only letters, digits, `_`, and `-`.
+
+Harness paths are derived from workflow ids. `wf_example` writes `.harness/example.sh`.
+
+## Commands
+
+```bash
+# Generate every workflow harness
+uv run flowsh .made/workflows.yml
+
+# Generate one workflow by id
+uv run flowsh .made/workflows.yml --workflow wf_example
+
+# Show planned outputs without writing files
+uv run flowsh .made/workflows.yml --dry-run
+
+# Overwrite existing harness files
+uv run flowsh .made/workflows.yml --force
+
+# Show version
+uv run flowsh --version
+```
+
+## CLI Contract
+
+`flowsh` is non-interactive. It never prompts for missing information.
+
+Current help output is plain text and deterministic across repeated runs:
+
+```text
+Usage: flowsh [OPTIONS] WORKFLOW_YAML
+
+  Generate reproducible OpenCode Bash harness scripts from MADE workflow YAML.
+
+Arguments:
+  WORKFLOW_YAML  Path to .made/workflows.yml  \[required]
+
+Options:
+  --workflow TEXT  Optional workflow id to generate. Defaults to all workflows.
+  --dry-run        Print planned output paths without writing scripts.
+  --force          Overwrite existing files. Without this, existing files cause a failure.
+  --version        Show the flowsh version and exit.
+  --help           Show this message and exit.
+```
+
+The CLI pins its help formatter width so this contract does not vary with the
+caller terminal size or `COLUMNS` environment value.
+
+Exit codes:
+
+| Case | Exit | stdout | stderr |
+|---|---:|---|---|
+| `--help` | `0` | Help text | Empty |
+| `--version` | `0` | `flowsh <version>` | 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 |
+| Malformed or unsupported workflow YAML | `1` | Empty | `ERROR: <reason>` |
+| Unknown `--workflow` id | `1` | Empty | `ERROR: No workflow id matched ...` with known workflow ids |
+| Existing harness without `--force` | `1` | Empty | `ERROR: Refusing to overwrite ...` |
+| Output directory/path safety failure | `1` | Empty | `ERROR: <path safety reason>` |
+
+Generated harnesses are also non-interactive. `harness.sh --dry-run` exits `0` after logging planned steps to stderr and creating no log directory. A real harness run exits `0` only after every step succeeds. Failed `bash`, `vars`, or `agent` steps return the failing command status, log `Step failed: <step> (exit=<code>)` to stderr, and stop before later steps run. If an `agent` step runs without `opencode` on `PATH`, the harness exits `127` and prints `opencode CLI not found in PATH` to stderr.
+
+Generated harnesses are written with owner-only executable permissions and refuse to overwrite existing paths unless `--force` is passed. Multi-workflow generation preflights overwrite conflicts before writing any harness. `--force` replaces regular harness files and harness-file symlinks, but never replaces a directory at a harness file path. The `.harness` output directory must be a real directory, not a symlink or file. Harness dry runs do not create log files or directories. Real harness logs go to `.flowsh/logs` by default with owner-private directory and file permissions. Set `FLOWSH_LOG_DIR` when running a harness to use another local relative log directory; absolute paths, `..` path segments, symlinked path components, and non-directory log paths are refused. Logging setup and write failures fail the harness instead of being silently ignored.
+
+Generated `bash` and `vars` bodies run with `bash -euo pipefail`, so command failures stop the workflow instead of being masked by later successful commands. Captured `vars` values are exported for later `bash` steps. `agent` steps invoke only `opencode run --format json -- <prompt>` with optional `--agent <agent>` before `--`, so dash-prefixed prompts are message content rather than OpenCode flags. Agent steps fail with a clear error if `opencode` is not on `PATH`.
+
+## Development
+
+```bash
+uv sync
+make install
+make build
+make qa
+make hygiene
+make clean
+```
+
+`make install` installs `flowsh` into the user PATH with `uv tool install --force .`.
+`make build` creates reproducible source and wheel distributions under ignored `dist/`.
+
+`make qa` runs Ruff, Python compile checks, and pytest with locked dependencies, then builds packages locally and in CI.
+The pytest suite also verifies `python -m flowsh`, `uv run flowsh`, and the direct
+`scripts/workflow_to_harness.py` entrypoint against the same help contract.
+`make hygiene` prints tracked, untracked, and ignored files with
+`git status --short --ignored`; review it before release to confirm only intended
+source changes are present and generated artifacts remain ignored. `make clean`
+removes local caches, build outputs, generated harnesses, and generated logs.
+
+There is no TypeScript compiler, template system, DSL explorer, legacy node
+registry, or archived legacy workflow spec in this repository.

flowsh_cli-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["uv_build>=0.9.9,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "flowsh-cli"
+version = "0.1.0"
+description = "Generate Bash harness scripts from MADE workflow YAML files."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+classifiers = [
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "PyYAML>=6,<7",
+  "pydantic>=2,<3",
+  "typer>=0.20,<0.21",
+]
+
+[project.urls]
+Homepage = "https://github.com/tbrandenburg/flowsh"
+Source = "https://github.com/tbrandenburg/flowsh"
+
+[project.scripts]
+flowsh = "flowsh_cli.cli:main"
+
+[dependency-groups]
+dev = [
+  "pytest>=8,<9",
+  "ruff>=0.14,<0.15",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

flowsh_cli-0.1.0/src/flowsh_cli/__init__.py

@@ -0,0 +1,15 @@
+"""flowsh: generate OpenCode Bash harness scripts from workflow YAML."""
+
+from flowsh_cli.models import Workflow, WorkflowParseError, parse_workflows
+from flowsh_cli.render import harness_path, render_harness
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Workflow",
+    "WorkflowParseError",
+    "__version__",
+    "harness_path",
+    "parse_workflows",
+    "render_harness",
+]

flowsh_cli-0.1.0/src/flowsh_cli/__main__.py

@@ -0,0 +1,4 @@
+from flowsh_cli.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flowsh_cli-0.1.0/src/flowsh_cli/cli.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from flowsh_cli import __version__
+from flowsh_cli.models import Workflow, WorkflowParseError, parse_workflows
+from flowsh_cli.render import harness_path, render_harness
+
+app = typer.Typer(
+    add_completion=False,
+    context_settings={"terminal_width": 120, "max_content_width": 120},
+    help="Generate reproducible OpenCode Bash harness scripts from MADE workflow YAML.",
+    pretty_exceptions_enable=False,
+    rich_markup_mode=None,
+)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    try:
+        app(args=list(argv) if argv is not None else None, prog_name="flowsh")
+    except SystemExit as error:
+        return error.code if isinstance(error.code, int) else 1
+
+    return 0
+
+
+@app.command(help="Generate reproducible OpenCode Bash harness scripts from MADE workflow YAML.")
+def generate(
+    workflow_yaml: Annotated[Path, typer.Argument(help="Path to .made/workflows.yml")],
+    workflow: Annotated[
+        str | None,
+        typer.Option(
+            "--workflow",
+            help="Optional workflow id to generate. Defaults to all workflows.",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Print planned output paths without writing scripts."),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            help="Overwrite existing files. Without this, existing files cause a failure.",
+        ),
+    ] = False,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=lambda value: print_version(value),
+            help="Show the flowsh version and exit.",
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """Generate Bash harnesses from workflow YAML."""
+
+    _ = version
+
+    try:
+        workflows = parse_workflows(workflow_yaml)
+        selected = select_workflows(workflows, workflow)
+        write_harnesses(selected, dry_run=dry_run, force=force)
+    except WorkflowParseError as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        raise typer.Exit(1) from error
+    except OSError as error:
+        print(f"ERROR: Cannot write harness: {error}", file=sys.stderr)
+        raise typer.Exit(1) from error
+
+
+def select_workflows(workflows: list[Workflow], selector: str | None) -> list[Workflow]:
+    if selector is None:
+        return workflows
+
+    matches = [workflow for workflow in workflows if workflow.id == selector]
+    if matches:
+        return matches
+
+    known = ", ".join(f"{workflow.name} ({workflow.id})" for workflow in workflows)
+    raise WorkflowParseError(f"No workflow id matched {selector!r}. Known workflows: {known}")
+
+
+def print_version(value: bool) -> None:
+    if not value:
+        return
+
+    print(f"flowsh {__version__}")
+    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]
+
+    if dry_run:
+        for workflow, output_path in output_paths:
+            print(f"DRY-RUN would write {output_path} for workflow {workflow.name!r}")
+        return
+
+    directory_conflicts = [path for _, path in output_paths if path.exists() and path.is_dir()]
+    if directory_conflicts:
+        conflict_list = ", ".join(str(path) for path in directory_conflicts)
+        raise WorkflowParseError(f"Output path exists but is a directory: {conflict_list}")
+
+    if not force:
+        conflicts = [path for _, path in output_paths if path.exists() or path.is_symlink()]
+        if conflicts:
+            conflict_list = ", ".join(str(path) for path in conflicts)
+            message = f"Refusing to overwrite existing file(s): {conflict_list} (use --force)"
+            raise WorkflowParseError(message)
+
+    rendered_harnesses = [
+        (output_path, render_harness(workflow)) for workflow, output_path in output_paths
+    ]
+
+    for output_path, script in rendered_harnesses:
+        if (output_path.exists() or output_path.is_symlink()) and not force:
+            message = f"Refusing to overwrite existing file: {output_path} (use --force)"
+            raise WorkflowParseError(message)
+
+        ensure_output_directory(output_path.parent)
+        write_executable(output_path, script)
+        print(f"Wrote {output_path}")
+
+
+def ensure_output_directory(path: Path) -> None:
+    if path.is_symlink():
+        raise WorkflowParseError(f"Refusing to write through symlinked directory: {path}")
+    if path.exists() and not path.is_dir():
+        raise WorkflowParseError(f"Output path exists but is not a directory: {path}")
+
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def write_executable(output_path: Path, content: str) -> None:
+    temporary_path: Path | None = None
+
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=output_path.parent,
+            prefix=f".{output_path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as temporary:
+            temporary_path = Path(temporary.name)
+            temporary.write(content)
+            temporary.write("\n")
+            temporary.flush()
+            os.fsync(temporary.fileno())
+
+        temporary_path.chmod(stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR)
+        temporary_path.replace(output_path)
+        fsync_directory(output_path.parent)
+    except OSError:
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+        raise
+
+
+def fsync_directory(path: Path) -> None:
+    try:
+        descriptor = os.open(path, os.O_RDONLY)
+    except OSError:
+        return
+
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)

flowsh_cli-0.1.0/src/flowsh_cli/models.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Annotated, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+MAX_WORKFLOW_YAML_BYTES = 1_048_576
+
+
+class WorkflowParseError(ValueError):
+    """Raised when the input YAML cannot be parsed or validated."""
+
+
+class UniqueKeySafeLoader(yaml.SafeLoader):
+    """YAML loader that rejects duplicate mapping keys instead of overwriting them."""
+
+    def compose_node(self, parent: object, index: object) -> yaml.nodes.Node:
+        if self.check_event(yaml.AliasEvent):
+            event = self.get_event()
+            raise yaml.constructor.ConstructorError(
+                "while composing a node",
+                event.start_mark,
+                "YAML aliases are not supported",
+                event.start_mark,
+            )
+
+        return super().compose_node(parent, index)
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+
+class BaseStep(StrictModel):
+    name: str | None = None
+
+    @field_validator("name")
+    @classmethod
+    def validate_optional_string(cls, value: str | None) -> str | None:
+        if value is not None and value.strip() == "":
+            raise ValueError("must not be empty")
+        if value is not None and has_control_characters(value):
+            raise ValueError("must not contain control characters")
+        return value
+
+
+class BashStep(BaseStep):
+    type: Literal["bash"]
+    run: str
+
+    @field_validator("run")
+    @classmethod
+    def validate_run(cls, value: str) -> str:
+        if value.strip() == "":
+            raise ValueError("must not be empty")
+        if has_unsafe_control_characters(value):
+            raise ValueError("must not contain unsafe control characters")
+        return value
+
+
+class AgentStep(BaseStep):
+    type: Literal["agent"]
+    prompt: str
+    agent: str | None = None
+
+    @field_validator("prompt", "agent")
+    @classmethod
+    def validate_strings(cls, value: str | None) -> str | None:
+        if value is not None and value.strip() == "":
+            raise ValueError("must not be empty")
+        if value is not None and has_unsafe_control_characters(value):
+            raise ValueError("must not contain unsafe control characters")
+        return value
+
+    @field_validator("agent")
+    @classmethod
+    def validate_agent(cls, value: str | None) -> str | None:
+        if value is not None and not re.fullmatch(r"[A-Za-z0-9_-]+", value):
+            raise ValueError("must match ^[A-Za-z0-9_-]+$")
+        return value
+
+
+class VarsStep(BaseStep):
+    type: Literal["vars"]
+    values: dict[str, str]
+
+    @field_validator("values")
+    @classmethod
+    def validate_values(cls, value: dict[str, str]) -> dict[str, str]:
+        if not value:
+            raise ValueError("must contain at least one variable")
+
+        for name, command in value.items():
+            if not re.fullmatch(r"[A-Z_][A-Z0-9_]*", name):
+                raise ValueError(f"invalid variable name: {name}")
+            if command.strip() == "":
+                raise ValueError(f"empty command for variable: {name}")
+            if has_unsafe_control_characters(command):
+                raise ValueError(f"unsafe control character in command for variable: {name}")
+
+        return value
+
+
+Step = Annotated[VarsStep | BashStep | AgentStep, Field(discriminator="type")]
+
+
+class Workflow(StrictModel):
+    id: str
+    name: str
+    steps: list[Step]
+
+    @field_validator("id")
+    @classmethod
+    def validate_id(cls, value: str) -> str:
+        if not re.fullmatch(r"wf_[A-Za-z0-9_-]+", value):
+            raise ValueError("must match ^wf_[A-Za-z0-9_-]+$")
+        return value
+
+    @field_validator("name")
+    @classmethod
+    def validate_non_empty(cls, value: str) -> str:
+        if value.strip() == "":
+            raise ValueError("must not be empty")
+        if has_control_characters(value):
+            raise ValueError("must not contain control characters")
+        return value
+
+    @field_validator("steps")
+    @classmethod
+    def validate_steps(cls, value: list[Step]) -> list[Step]:
+        if not value:
+            raise ValueError("must contain at least one step")
+        return value
+
+
+class WorkflowFile(StrictModel):
+    workflows: list[Workflow]
+
+    @field_validator("workflows")
+    @classmethod
+    def validate_workflows(cls, value: list[Workflow]) -> list[Workflow]:
+        if not value:
+            raise ValueError("must contain at least one workflow")
+
+        id_counts = Counter(workflow.id for workflow in value)
+        duplicate_ids = sorted(workflow_id for workflow_id, count in id_counts.items() if count > 1)
+        if duplicate_ids:
+            raise ValueError(f"duplicate workflow ids: {', '.join(duplicate_ids)}")
+
+        return value
+
+
+def parse_workflows(path: Path) -> list[Workflow]:
+    validate_workflow_file_path(path)
+    content = read_workflow_text(path)
+
+    try:
+        data = yaml.load(content, Loader=UniqueKeySafeLoader)
+    except yaml.YAMLError as error:
+        raise WorkflowParseError(f"Invalid YAML: {error}") from error
+
+    if data is None:
+        raise WorkflowParseError("Workflow YAML must not be empty")
+    if not isinstance(data, Mapping):
+        raise WorkflowParseError("Workflow YAML root must be a mapping with a 'workflows' key")
+
+    try:
+        return WorkflowFile.model_validate(data).workflows
+    except ValidationError as error:
+        raise WorkflowParseError(format_validation_error(error)) from error
+
+
+def format_validation_error(error: ValidationError) -> str:
+    messages: list[str] = []
+    for item in error.errors(include_url=False, include_input=False, include_context=False):
+        location = ".".join(str(part) for part in item["loc"])
+        message = str(item["msg"])
+        if location:
+            messages.append(f"{location}: {message}")
+            continue
+
+        messages.append(message)
+
+    return "Invalid workflow YAML: " + "; ".join(messages)
+
+
+def construct_unique_mapping(
+    loader: UniqueKeySafeLoader,
+    node: yaml.nodes.MappingNode,
+    deep: bool = False,
+) -> object:
+    seen: set[object] = set()
+    for key_node, _ in node.value:
+        key = loader.construct_object(key_node, deep=deep)
+        try:
+            duplicate = key in seen
+        except TypeError as error:
+            raise yaml.constructor.ConstructorError(
+                "while constructing a mapping",
+                node.start_mark,
+                "found unhashable mapping key",
+                key_node.start_mark,
+            ) from error
+        if duplicate:
+            raise yaml.constructor.ConstructorError(
+                "while constructing a mapping",
+                node.start_mark,
+                f"found duplicate key: {key}",
+                key_node.start_mark,
+            )
+        seen.add(key)
+
+    return yaml.SafeLoader.construct_mapping(loader, node, deep=deep)
+
+
+UniqueKeySafeLoader.add_constructor(
+    yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG,
+    construct_unique_mapping,
+)
+
+
+def validate_workflow_file_path(path: Path) -> None:
+    try:
+        metadata = path.stat()
+    except OSError as error:
+        raise WorkflowParseError(f"Cannot stat workflow YAML: {error}") from error
+
+    if not path.is_file():
+        raise WorkflowParseError(f"Workflow YAML must be a regular file: {path}")
+    if metadata.st_size > MAX_WORKFLOW_YAML_BYTES:
+        raise WorkflowParseError(
+            f"Workflow YAML is too large: {metadata.st_size} bytes "
+            f"(max {MAX_WORKFLOW_YAML_BYTES} bytes)"
+        )
+
+
+def read_workflow_text(path: Path) -> str:
+    try:
+        with path.open("rb") as workflow_file:
+            content = workflow_file.read(MAX_WORKFLOW_YAML_BYTES + 1)
+    except OSError as error:
+        raise WorkflowParseError(f"Cannot read workflow YAML: {error}") from error
+
+    if len(content) > MAX_WORKFLOW_YAML_BYTES:
+        raise WorkflowParseError(
+            f"Workflow YAML is too large: more than {MAX_WORKFLOW_YAML_BYTES} bytes"
+        )
+
+    try:
+        return content.decode("utf-8")
+    except UnicodeError as error:
+        raise WorkflowParseError(f"Workflow YAML must be valid UTF-8: {error}") from error
+
+
+def has_control_characters(value: str) -> bool:
+    return any(ord(character) < 32 or ord(character) == 127 for character in value)
+
+
+def has_unsafe_control_characters(value: str) -> bool:
+    allowed = {"\n", "\t"}
+    return any(
+        character not in allowed and (ord(character) < 32 or ord(character) == 127)
+        for character in value
+    )

flowsh_cli-0.1.0/src/flowsh_cli/render.py

@@ -0,0 +1,339 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from flowsh_cli.models import AgentStep, BashStep, Step, VarsStep, Workflow
+
+
+def harness_path(workflow: Workflow) -> Path:
+    return Path(".harness") / f"{workflow.id.removeprefix('wf_')}.sh"
+
+
+def render_harness(workflow: Workflow) -> str:
+    script_name = harness_path(workflow).name
+    lines: list[str] = [
+        "#!/usr/bin/env bash",
+        "set -euo pipefail",
+        "umask 077",
+        "",
+        f"SCRIPT_NAME={bash_quote(script_name)}",
+        'WORKFLOW_NAME="${SCRIPT_NAME%.sh}"',
+        "WORKFLOW_SLUG=$(printf '%s' \"$WORKFLOW_NAME\" \\",
+        "  | tr '[:upper:]' '[:lower:]' \\",
+        "  | sed -E 's/[^a-z0-9-]+/-/g; s/^-+//; s/-+$//; s/-+/-/g')",
+        "LOG_TIMESTAMP=\"$(date -u +'%Y%m%dT%H%M%SZ')\"",
+        '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",
+        "",
+        section("refuse_symlink_path() - keep generated logs inside plain relative paths"),
+        "refuse_symlink_path() {",
+        '  local target="$1"',
+        "",
+        '  if [[ -z "$target" ]]; then',
+        '    printf "ERROR: Log directory must not be empty\\n" >&2',
+        "    return 1",
+        "  fi",
+        '  if [[ "$target" == /* ]]; then',
+        '    printf "ERROR: Log directory must be relative: %s\\n" "$target" >&2',
+        "    return 1",
+        "  fi",
+        "",
+        "  local current=",
+        "  local part",
+        '  IFS=/ read -r -a path_parts <<< "$target"',
+        '  for part in "${path_parts[@]}"; do',
+        '    if [[ -z "$part" || "$part" == "." ]]; then',
+        "      continue",
+        "    fi",
+        '    if [[ "$part" == ".." ]]; then',
+        "      printf '%s: %s\\n' "
+        '"ERROR: Log directory must not contain .. path segments" "$target" >&2',
+        "      return 1",
+        "    fi",
+        '    current="${current:+${current}/}${part}"',
+        '    if [[ -L "$current" ]]; then',
+        '      printf "ERROR: Refusing to write logs through symlinked path: %s\\n" "$current" >&2',
+        "      return 1",
+        "    fi",
+        "  done",
+        "}",
+        "",
+        section("Log file setup - local by default, override with FLOWSH_LOG_DIR"),
+        'LOG_DIR="${FLOWSH_LOG_DIR:-.flowsh/logs}"',
+        "LOG_FILE=",
+        'if [[ "$DRY_RUN" == false ]]; then',
+        '  refuse_symlink_path "$LOG_DIR" || exit 1',
+        '  if [[ -e "$LOG_DIR" && ! -d "$LOG_DIR" ]]; then',
+        '    printf "ERROR: Log path exists but is not a directory: %s\\n" "$LOG_DIR" >&2',
+        "    exit 1",
+        "  fi",
+        '  if ! mkdir -p "$LOG_DIR"; then',
+        '    printf "ERROR: Cannot create log directory: %s\\n" "$LOG_DIR" >&2',
+        "    exit 1",
+        "  fi",
+        '  refuse_symlink_path "$LOG_DIR" || exit 1',
+        '  if [[ ! -d "$LOG_DIR" ]]; then',
+        '    printf "ERROR: Log path exists but is not a directory: %s\\n" "$LOG_DIR" >&2',
+        "    exit 1",
+        "  fi",
+        '  if ! chmod 700 "$LOG_DIR"; then',
+        '    printf "ERROR: Cannot set log directory permissions: %s\\n" "$LOG_DIR" >&2',
+        "    exit 1",
+        "  fi",
+        '  LOG_FILE="${LOG_DIR}/${LOG_BASENAME}"',
+        '  if ! : > "$LOG_FILE"; then',
+        '    printf "ERROR: Cannot create log file: %s\\n" "$LOG_FILE" >&2',
+        "    exit 1",
+        "  fi",
+        '  if ! chmod 600 "$LOG_FILE"; then',
+        '    printf "ERROR: Cannot set log file permissions: %s\\n" "$LOG_FILE" >&2',
+        "    exit 1",
+        "  fi",
+        "fi",
+        "",
+        section("log() - ISO-8601 UTC timestamps, INFO/ERROR, stderr + log file"),
+        "log() {",
+        '  local level="$1"; shift',
+        "  local message",
+        "  message=\"$(date -u +'%Y-%m-%dT%H:%M:%SZ') [${level}] $*\"",
+        "  printf '%s\\n' \"$message\" >&2",
+        '  if [[ -n "$LOG_FILE" ]]; then',
+        '    if ! printf \'%s\\n\' "$message" >> "$LOG_FILE"; then',
+        '      printf "ERROR: Cannot write log file: %s\\n" "$LOG_FILE" >&2',
+        "      exit 1",
+        "    fi",
+        "  fi",
+        "}",
+        "",
+        section("catch() - centralized step failure hook"),
+        "catch() {",
+        '  local step_name="$1"',
+        '  local exit_code="$2"',
+        '  log ERROR "Step failed: ${step_name} (exit=${exit_code})"',
+        "}",
+        "",
+        section("run_step() - dry-run and failure handling; streams output via tee"),
+        "run_step() {",
+        '  local step_name="$1"',
+        "",
+        '  if [[ "$DRY_RUN" == true ]]; then',
+        '    log INFO "[DRY-RUN] would run: ${step_name}"',
+        "    return 0",
+        "  fi",
+        "",
+        '  log INFO "Running step: ${step_name}"',
+        "",
+        "  set +e",
+        '  if ( : >> "$LOG_FILE" ) 2>/dev/null; then',
+        '    "$step_name" > >(tee -a "$LOG_FILE") 2> >(tee -a "$LOG_FILE" >&2)',
+        "    local status=$?",
+        "  else",
+        '    "$step_name"',
+        "    local status=$?",
+        "  fi",
+        "  set -e",
+        "",
+        "  if [[ $status -ne 0 ]]; then",
+        '    catch "$step_name" "$status"',
+        "  fi",
+        '  return "$status"',
+        "}",
+        "",
+        section("run_stateful_step() - dry-run and failure handling without subshells"),
+        "run_stateful_step() {",
+        '  local step_name="$1"',
+        "",
+        '  if [[ "$DRY_RUN" == true ]]; then',
+        '    log INFO "[DRY-RUN] would run: ${step_name}"',
+        "    return 0",
+        "  fi",
+        "",
+        '  log INFO "Running step: ${step_name}"',
+        "",
+        "  set +e",
+        '  "$step_name"',
+        "  local status=$?",
+        "  set -e",
+        "",
+        "  if [[ $status -ne 0 ]]; then",
+        '    catch "$step_name" "$status"',
+        "  fi",
+        '  return "$status"',
+        "}",
+        "",
+        section("run_agent() - prompt handling and OpenCode CLI invocation"),
+        "run_agent() {",
+        '  local prompt="$1"',
+        '  local agent="${2:-}"',
+        "",
+        "  local cmd=(opencode run --format json)",
+        '  if [[ -n "$agent" ]]; then',
+        '    cmd+=(--agent "$agent")',
+        "  fi",
+        "",
+        '  if [[ "$DRY_RUN" == true ]]; then',
+        '    log INFO "[DRY-RUN] would run: $(printf \'%q \' "${cmd[@]}") (with prompt)"',
+        "    return 0",
+        "  fi",
+        "",
+        "  if ! command -v opencode >/dev/null 2>&1; then",
+        '    log ERROR "opencode CLI not found in PATH"',
+        "    return 127",
+        "  fi",
+        "",
+        '  "${cmd[@]}" -- "$prompt"',
+        "}",
+        "",
+        section(f"Starting workflow: {workflow.name}"),
+        f"log INFO {bash_quote(f'Starting workflow: {workflow.name}')}",
+        "",
+    ]
+
+    used_function_names: set[str] = set()
+    for index, step in enumerate(workflow.steps, start=1):
+        lines.extend(render_step(index, step, used_function_names))
+
+    lines.extend(
+        [
+            section(f"Workflow finished: {workflow.name}"),
+            f"log INFO {bash_quote(f'Workflow finished: {workflow.name}')}",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+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}() {{"]
+
+    if isinstance(step, VarsStep):
+        lines.append("  local status=0")
+        for name, command in step.values.items():
+            delimiter = heredoc_delimiter(f"VARS_{name}", command)
+            lines.append(f"  {name}=$(bash -euo pipefail <<'{delimiter}'")
+            lines.extend(script_lines(command))
+            lines.extend(
+                [
+                    delimiter,
+                    "  )",
+                    "  status=$?",
+                    "  if [[ $status -ne 0 ]]; then",
+                    '    return "$status"',
+                    "  fi",
+                    f"  export {name}",
+                ]
+            )
+    elif isinstance(step, BashStep):
+        delimiter = heredoc_delimiter("BASH", step.run)
+        lines.extend(
+            [
+                f"  bash -euo pipefail <<'{delimiter}'",
+                *step.run.strip().splitlines(),
+                delimiter,
+            ]
+        )
+    elif isinstance(step, AgentStep):
+        delimiter = heredoc_delimiter("PROMPT", step.prompt)
+        lines.extend(
+            [
+                "  local prompt",
+                f"  prompt=$(cat <<'{delimiter}'",
+                *step.prompt.splitlines(),
+                delimiter,
+                "  )",
+            ]
+        )
+        if step.agent:
+            lines.append(f"  local agent={bash_quote(step.agent)}")
+            lines.append('  run_agent "$prompt" "$agent"')
+        else:
+            lines.append('  run_agent "$prompt"')
+    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 default_step_title(index: int, step: Step) -> str:
+    if isinstance(step, VarsStep):
+        return ", ".join(step.values.keys())
+    if isinstance(step, BashStep):
+        return truncate_one_line(step.run)
+    if isinstance(step, AgentStep):
+        return truncate_one_line(step.prompt)
+    return f"step {index}"
+
+
+def truncate_one_line(text: str, limit: int = 80) -> str:
+    compact = re.sub(r"\s+", " ", text).strip()
+    if len(compact) <= limit:
+        return compact
+    return compact[: limit - 1] + "..."
+
+
+def step_function_name(
+    index: int,
+    name: str | None,
+    used_function_names: set[str] | None = None,
+) -> str:
+    source = name or f"step_{index}"
+    slug = re.sub(r"[^A-Za-z0-9_]+", "_", source).strip("_")
+    if not slug:
+        slug = f"step_{index}"
+    if slug[0].isdigit():
+        slug = f"step_{slug}"
+    if not slug.startswith("step_"):
+        slug = f"step_{slug}"
+    base = slug.lower()
+    if used_function_names is None:
+        return base
+
+    function_name = base
+    suffix = 2
+    while function_name in used_function_names:
+        function_name = f"{base}_{suffix}"
+        suffix += 1
+
+    used_function_names.add(function_name)
+    return function_name
+
+
+def heredoc_delimiter(base: str, text: str) -> str:
+    delimiter = f"{base}_EOF"
+    counter = 1
+    while delimiter in text:
+        counter += 1
+        delimiter = f"{base}_EOF_{counter}"
+    return delimiter
+
+
+def script_lines(script: str) -> list[str]:
+    return script.strip().splitlines()
+
+
+def bash_quote(value: str) -> str:
+    return "'" + value.replace("'", "'\\''") + "'"
+
+
+def section(title: str) -> str:
+    safe_title = truncate_one_line(title, limit=120)
+    return "\n".join(
+        [
+            "# ---------------------------------------------------------------------------",
+            f"# {safe_title}",
+            "# ---------------------------------------------------------------------------",
+        ]
+    )