clm-kernel 0.0.0__py3-none-any.whl

clm/layer4/action_commands.py

@@ -0,0 +1,719 @@
+"""CLI Subcommands for Action and Workflow Execution, Validation, and Catalog (Sprint 396 / DEL-396-01).
+
+Provides user-facing command-line operations:
+- clm action validate <action.yaml> [--json]
+- clm action run <action.yaml> [--input <uri_or_path>] [--bind key=val...] [--output-handle <name>] [--json] [--dry-run]
+- clm action list [--catalog-dir <path>] [--json]
+- clm workflow validate <workflow.yaml> [--json]
+- clm workflow run <workflow.yaml> [--bind key=val...] [--workers <int>] [--json]
+
+Acceptance Criteria:
+- AC-396-01-01: clm action validate <path> returns 0 for valid manifests, non-zero for invalid ones.
+- AC-396-01-02: clm action run <path> executes action, commits output MCard, outputs VCard receipt, and exits 0.
+- AC-396-01-03: clm workflow run <path> executes multi-step DAG and returns all terminal MCard URIs.
+
+Layer 4 module.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import ValidationError as JsonSchemaValidationError
+from jsonschema import validate
+
+from clm.cross_cutting.clm_logger import get_logger
+from clm.cross_cutting.domain_models import MCard
+from clm.layer0.exceptions import CLMError
+from clm.layer0.model.action import ActionManifest
+from clm.layer0.model.workflow import WorkflowManifest
+from clm.layer1.hoare_sandwich import HoareSandwichEngine, HoareSandwichResult
+from clm.layer1.pocketflow_orchestrator import (
+    PocketFlowWorkflowOrchestrator,
+    WorkflowExecutionResult,
+)
+from clm.layer2.ingest import get_default_fs, ingest_file
+from clm.layer2.mcard_fs import MCardFileSystem
+
+_logger = get_logger("clm.layer4.action_commands")
+
+_REPO_ROOT = Path(__file__).resolve().parents[4]
+_ACTION_SCHEMA_PATH = _REPO_ROOT / "types" / "schemas" / "action_schema.json"
+_WORKFLOW_SCHEMA_PATH = _REPO_ROOT / "types" / "schemas" / "workflow_schema.json"
+
+
+def _load_schema(schema_path: Path) -> dict[str, Any]:
+    if not schema_path.is_file():
+        alt_path = Path.cwd() / "types" / "schemas" / schema_path.name
+        if alt_path.is_file():
+            return json.loads(alt_path.read_text(encoding="utf-8"))
+        raise FileNotFoundError(f"Cannot locate schema at {schema_path}")
+    return json.loads(schema_path.read_text(encoding="utf-8"))
+
+
+def _parse_input_bindings(
+    bindings_list: list[str] | None,
+    fs: MCardFileSystem | None = None,
+) -> dict[str, Any]:
+    """Parse list of 'key=val' strings, auto-ingesting local file paths into CAS."""
+    bindings: dict[str, Any] = {}
+    if not bindings_list:
+        return bindings
+
+    target_fs = fs or get_default_fs()
+    for item in bindings_list:
+        if "=" not in item:
+            continue
+        key, val = item.split("=", 1)
+        key = key.strip()
+        val = val.strip()
+
+        # Check if val is a local file that should be auto-ingested
+        val_path = Path(val)
+        if val_path.is_file() and not val.startswith("mcard:"):
+            try:
+                card = ingest_file(path=val_path, fs=target_fs)
+                bindings[key] = card
+                continue
+            except Exception as e:
+                _logger.warning(f"Could not auto-ingest file '{val}' into CAS: {e}")
+                bindings[key] = val_path.read_text(encoding="utf-8")
+                continue
+
+        # Check if val is an mcard URI
+        if val.startswith("mcard:") or val.startswith("mcard://"):
+            clean_uri = val
+            if clean_uri.startswith("mcard://"):
+                clean_uri = "mcard:" + clean_uri[len("mcard://") :]
+            try:
+                card = target_fs.read_file(clean_uri)
+                if card is not None:
+                    bindings[key] = card
+                    continue
+            except Exception as e:
+                _logger.debug(f"Could not resolve MCard from {clean_uri}: {e}")
+
+        bindings[key] = val
+    return bindings
+
+
+# ── Action CLI Commands ──────────────────────────────────────────────
+
+
+def action_validate_cmd(path: str, as_json: bool = False) -> int:
+    """AC-396-01-01: Validate an Action manifest against JSON Schema & Pydantic domain model."""
+    manifest_path = Path(path)
+    if not manifest_path.is_file():
+        err_msg = f"Action manifest file not found: {path}"
+        if as_json:
+            print(json.dumps({"status": "error", "error": err_msg}))
+        else:
+            print(f"❌ Error: {err_msg}")
+        return 1
+
+    try:
+        content = manifest_path.read_text(encoding="utf-8")
+        raw_dict = (
+            yaml.safe_load(content)
+            if manifest_path.suffix in (".yaml", ".yml")
+            else json.loads(content)
+        )
+
+        if not isinstance(raw_dict, dict):
+            raise ValueError("Manifest content must be a JSON/YAML mapping")
+
+        schema = _load_schema(_ACTION_SCHEMA_PATH)
+        validate(instance=raw_dict, schema=schema)
+
+        manifest = ActionManifest.from_dict(raw_dict)
+
+        if as_json:
+            print(
+                json.dumps(
+                    {
+                        "status": "valid",
+                        "name": manifest.clm.name,
+                        "operator": manifest.clm.operator,
+                        "inputs": [i.name for i in manifest.inputs],
+                        "outputs": [o.name for o in manifest.outputs],
+                        "preconditions": len(manifest.preconditions),
+                        "postconditions": len(manifest.postconditions),
+                    },
+                    indent=2,
+                )
+            )
+        else:
+            print(f"✅ Action manifest '{path}' is valid.")
+            print(f"   Name: {manifest.clm.name}")
+            print(f"   Operator: {manifest.clm.operator}")
+            print(f"   Inputs: {', '.join(i.name for i in manifest.inputs)}")
+            print(f"   Outputs: {', '.join(o.name for o in manifest.outputs)}")
+            print(
+                f"   Hoare Sandwich: {len(manifest.preconditions)} pre-conditions, {len(manifest.postconditions)} post-conditions"
+            )
+        return 0
+
+    except (JsonSchemaValidationError, ValueError, CLMError) as e:
+        if as_json:
+            print(json.dumps({"status": "invalid", "file": path, "error": str(e)}))
+        else:
+            print(f"❌ Validation failed for '{path}': {e}")
+        return 1
+    except Exception as e:
+        if as_json:
+            print(json.dumps({"status": "error", "file": path, "error": str(e)}))
+        else:
+            print(f"❌ Unexpected error validating '{path}': {e}")
+        return 1
+
+
+def action_run_cmd(
+    path: str,
+    input_uri: str | None = None,
+    bindings: list[str] | None = None,
+    output_handle: str | None = None,
+    as_json: bool = False,
+    dry_run: bool = False,
+    fs: MCardFileSystem | None = None,
+) -> int:
+    """AC-396-01-02: Execute an Action manifest within the Hoare Sandwich."""
+    manifest_path = Path(path)
+    if not manifest_path.is_file():
+        err_msg = f"Action manifest file not found: {path}"
+        if as_json:
+            print(json.dumps({"status": "error", "error": err_msg}))
+        else:
+            print(f"❌ Error: {err_msg}")
+        return 1
+
+    target_fs = fs or get_default_fs()
+
+    try:
+        manifest = ActionManifest.from_yaml(manifest_path)
+    except Exception as e:
+        err_msg = f"Failed to parse Action manifest '{path}': {e}"
+        if as_json:
+            print(json.dumps({"status": "error", "error": err_msg}))
+        else:
+            print(f"❌ {err_msg}")
+        return 1
+
+    input_map = _parse_input_bindings(bindings, fs=target_fs)
+
+    if input_uri:
+        input_path = Path(input_uri)
+        resolved_card: Any = input_uri
+        if input_path.is_file() and not input_uri.startswith("mcard:"):
+            try:
+                resolved_card = ingest_file(path=input_path, fs=target_fs)
+            except Exception as e:
+                _logger.warning(f"Could not ingest '{input_uri}' into CAS: {e}")
+                resolved_card = input_path.read_text(encoding="utf-8")
+        elif input_uri.startswith("mcard:") or input_uri.startswith("mcard://"):
+            clean_uri = input_uri
+            if clean_uri.startswith("mcard://"):
+                clean_uri = "mcard:" + clean_uri[len("mcard://") :]
+            try:
+                card = target_fs.read_file(clean_uri)
+                if card is not None:
+                    resolved_card = card
+            except Exception as e:
+                _logger.debug(f"Could not resolve MCard from {clean_uri}: {e}")
+
+        if manifest.inputs:
+            primary_name = manifest.inputs[0].name
+            if primary_name not in input_map:
+                input_map[primary_name] = resolved_card
+        else:
+            input_map["input"] = resolved_card
+
+    # Resolve any remaining string URIs in input_map
+    for k, v in list(input_map.items()):
+        if isinstance(v, str) and (v.startswith("mcard:") or v.startswith("mcard://")):
+            clean_uri = v
+            if clean_uri.startswith("mcard://"):
+                clean_uri = "mcard:" + clean_uri[len("mcard://") :]
+            try:
+                card = target_fs.read_file(clean_uri)
+                if card is not None:
+                    input_map[k] = card
+            except Exception as e:
+                _logger.debug(f"Could not resolve MCard from {clean_uri}: {e}")
+
+    if dry_run:
+        input_descriptions = {}
+        for k, v in input_map.items():
+            if isinstance(v, MCard):
+                input_descriptions[k] = v.uri
+            else:
+                input_descriptions[k] = str(v)[:60]
+
+        dry_run_report = {
+            "status": "dry_run",
+            "action": manifest.clm.name,
+            "operator": manifest.clm.operator,
+            "resolved_inputs": input_descriptions,
+            "expected_outputs": [o.name for o in manifest.outputs],
+            "preconditions": [p.rule for p in manifest.preconditions],
+            "postconditions": [p.rule for p in manifest.postconditions],
+        }
+        if as_json:
+            print(json.dumps(dry_run_report, indent=2))
+        else:
+            print(f"🔍 Dry run successful for Action '{manifest.clm.name}':")
+            print(f"   Operator: {manifest.clm.operator}")
+            print(f"   Inputs: {input_descriptions}")
+            print(f"   Outputs: {[o.name for o in manifest.outputs]}")
+        return 0
+
+    try:
+        result: HoareSandwichResult = HoareSandwichEngine.execute(
+            manifest=manifest,
+            input_bindings=input_map,
+            fs=target_fs,
+        )
+
+        if result.is_success:
+            output_uris = {}
+            for name, card in result.outputs.items():
+                card_uri = card.uri
+                if card_uri.startswith("mcard:"):
+                    rest = card_uri[len("mcard:") :].lstrip("/")
+                    output_uris[name] = f"mcard://{rest}"
+                else:
+                    output_uris[name] = card_uri
+
+            receipt_uri = None
+            if result.receipt:
+                r_uri = result.receipt.uri
+                if r_uri.startswith("mcard:"):
+                    receipt_uri = f"mcard://{r_uri[len('mcard:'):].lstrip('/')}"
+                else:
+                    receipt_uri = r_uri
+
+            if as_json:
+                print(
+                    json.dumps(
+                        {
+                            "status": "success",
+                            "action": result.action_name,
+                            "outputs": output_uris,
+                            "receipt": receipt_uri,
+                            "metrics": result.metrics,
+                        },
+                        indent=2,
+                    )
+                )
+            else:
+                print(f"🚀 Action '{result.action_name}' executed successfully.")
+                for name, out_uri in output_uris.items():
+                    print(f"   Output [{name}]: {out_uri}")
+                if receipt_uri:
+                    print(f"   VCard Receipt: {receipt_uri}")
+                wall_ms = result.metrics.get("wall_time_ms", 0.0)
+                print(f"   Execution time: {wall_ms:.2f}ms")
+            return 0
+        else:
+            if as_json:
+                print(
+                    json.dumps(
+                        {
+                            "status": "failed",
+                            "action": result.action_name,
+                            "error": result.error,
+                            "rollback_occurred": result.rollback_occurred,
+                            "rollback_time_ms": result.rollback_time_ms,
+                        },
+                        indent=2,
+                    )
+                )
+            else:
+                print(f"❌ Action '{result.action_name}' failed: {result.error}")
+                if result.rollback_occurred:
+                    print(
+                        f"   Transactional rollback completed in {result.rollback_time_ms:.3f}ms"
+                    )
+            return 1
+
+    except Exception as e:
+        if as_json:
+            print(json.dumps({"status": "error", "error": str(e)}))
+        else:
+            print(f"❌ Execution exception: {e}")
+        return 1
+
+
+def action_list_cmd(
+    catalog_dir: str | None = None,
+    as_json: bool = False,
+) -> int:
+    """List exemplar actions available in the catalog."""
+    cat_path = Path(catalog_dir) if catalog_dir else (_REPO_ROOT / "sample_pcards" / "actions")
+
+    if not cat_path.is_dir():
+        err_msg = f"Catalog directory not found: {cat_path}"
+        if as_json:
+            print(json.dumps({"status": "error", "error": err_msg}))
+        else:
+            print(f"❌ Error: {err_msg}")
+        return 1
+
+    actions_info = []
+    for f in sorted(cat_path.iterdir()):
+        if f.suffix in (".yaml", ".yml", ".json") and f.name != "README.md":
+            try:
+                content = f.read_text(encoding="utf-8")
+                raw = (
+                    yaml.safe_load(content)
+                    if f.suffix in (".yaml", ".yml")
+                    else json.loads(content)
+                )
+                if isinstance(raw, dict) and raw.get("clm", {}).get("type") == "action":
+                    manifest = ActionManifest.from_dict(raw)
+                    actions_info.append(
+                        {
+                            "file": f.name,
+                            "name": manifest.clm.name,
+                            "operator": manifest.clm.operator,
+                            "description": manifest.clm.description or "",
+                            "inputs": [i.name for i in manifest.inputs],
+                            "outputs": [o.name for o in manifest.outputs],
+                        }
+                    )
+            except Exception:
+                continue
+
+    if as_json:
+        print(json.dumps({"catalog": str(cat_path), "actions": actions_info}, indent=2))
+    else:
+        print(f"📦 Canonical Exemplar Action Catalog ({cat_path}):")
+        print(f"{'Name':<35} {'Operator':<12} {'File':<30}")
+        print("-" * 80)
+        for act in actions_info:
+            print(f"{act['name']:<35} {act['operator']:<12} {act['file']:<30}")
+    return 0
+
+
+# ── Workflow CLI Commands ────────────────────────────────────────────
+
+
+def workflow_validate_cmd(path: str, as_json: bool = False) -> int:
+    """Validate a Workflow manifest against JSON Schema & Pydantic domain model."""
+    manifest_path = Path(path)
+    if not manifest_path.is_file():
+        err_msg = f"Workflow manifest file not found: {path}"
+        if as_json:
+            print(json.dumps({"status": "error", "error": err_msg}))
+        else:
+            print(f"❌ Error: {err_msg}")
+        return 1
+
+    try:
+        content = manifest_path.read_text(encoding="utf-8")
+        raw_dict = (
+            yaml.safe_load(content)
+            if manifest_path.suffix in (".yaml", ".yml")
+            else json.loads(content)
+        )
+
+        if not isinstance(raw_dict, dict):
+            raise ValueError("Manifest content must be a JSON/YAML mapping")
+
+        schema = _load_schema(_WORKFLOW_SCHEMA_PATH)
+        validate(instance=raw_dict, schema=schema)
+
+        workflow = WorkflowManifest.from_dict(raw_dict)
+
+        if as_json:
+            print(
+                json.dumps(
+                    {
+                        "status": "valid",
+                        "name": workflow.clm.name,
+                        "steps": len(workflow.steps),
+                        "inputs": [i.name for i in workflow.inputs],
+                        "outputs": [o.name for o in workflow.outputs],
+                    },
+                    indent=2,
+                )
+            )
+        else:
+            print(f"✅ Workflow manifest '{path}' is valid.")
+            print(f"   Name: {workflow.clm.name}")
+            print(f"   Steps: {len(workflow.steps)} DAG nodes")
+            print(f"   Inputs: {', '.join(i.name for i in workflow.inputs)}")
+            print(f"   Outputs: {', '.join(o.name for o in workflow.outputs)}")
+        return 0
+
+    except (JsonSchemaValidationError, ValueError, CLMError) as e:
+        if as_json:
+            print(json.dumps({"status": "invalid", "file": path, "error": str(e)}))
+        else:
+            print(f"❌ Validation failed for '{path}': {e}")
+        return 1
+    except Exception as e:
+        if as_json:
+            print(json.dumps({"status": "error", "file": path, "error": str(e)}))
+        else:
+            print(f"❌ Unexpected error validating '{path}': {e}")
+        return 1
+
+
+def workflow_run_cmd(
+    path: str,
+    bindings: list[str] | None = None,
+    as_json: bool = False,
+    fs: MCardFileSystem | None = None,
+    max_workers: int = 4,
+) -> int:
+    """AC-396-01-03: Execute a Pocket Flow Monadic Workflow DAG pipeline."""
+    manifest_path = Path(path)
+    if not manifest_path.is_file():
+        err_msg = f"Workflow manifest file not found: {path}"
+        if as_json:
+            print(json.dumps({"status": "error", "error": err_msg}))
+        else:
+            print(f"❌ Error: {err_msg}")
+        return 1
+
+    target_fs = fs or get_default_fs()
+
+    try:
+        content = manifest_path.read_text(encoding="utf-8")
+        raw = (
+            yaml.safe_load(content)
+            if manifest_path.suffix in (".yaml", ".yml")
+            else json.loads(content)
+        )
+        workflow = WorkflowManifest.from_dict(raw)
+    except Exception as e:
+        err_msg = f"Failed to parse Workflow manifest '{path}': {e}"
+        if as_json:
+            print(json.dumps({"status": "error", "error": err_msg}))
+        else:
+            print(f"❌ {err_msg}")
+        return 1
+
+    input_map = _parse_input_bindings(bindings, fs=target_fs)
+
+    # Resolve any mcard:// URIs into full MCard instances from CAS
+    for k, v in list(input_map.items()):
+        if isinstance(v, str) and (v.startswith("mcard:") or v.startswith("mcard://")):
+            clean_uri = v
+            if clean_uri.startswith("mcard://"):
+                clean_uri = "mcard:" + clean_uri[len("mcard://") :]
+            try:
+                card = target_fs.read_file(clean_uri)
+                if card is not None:
+                    input_map[k] = card
+            except Exception as e:
+                _logger.debug(f"Could not resolve MCard from {clean_uri}: {e}")
+
+    orchestrator = PocketFlowWorkflowOrchestrator(base_dir=manifest_path.parent)
+
+    try:
+        result: WorkflowExecutionResult = orchestrator.execute(
+            workflow=workflow,
+            inputs=input_map,
+            fs=target_fs,
+            max_workers=max_workers,
+            raise_on_failure=False,
+        )
+
+        if result.is_success:
+            output_uris = {}
+            for name, card in result.outputs.items():
+                c_uri = card.uri
+                if c_uri.startswith("mcard:"):
+                    output_uris[name] = f"mcard://{c_uri[len('mcard:'):].lstrip('/')}"
+                else:
+                    output_uris[name] = c_uri
+
+            receipt_uris = {}
+            for step_id, r_card in result.step_receipts.items():
+                r_uri = r_card.uri
+                if r_uri.startswith("mcard:"):
+                    receipt_uris[step_id] = f"mcard://{r_uri[len('mcard:'):].lstrip('/')}"
+                else:
+                    receipt_uris[step_id] = r_uri
+
+            if as_json:
+                print(
+                    json.dumps(
+                        {
+                            "status": "success",
+                            "workflow": result.workflow_name,
+                            "outputs": output_uris,
+                            "receipts": receipt_uris,
+                            "metrics": result.metrics,
+                        },
+                        indent=2,
+                    )
+                )
+            else:
+                print(f"🚀 Workflow '{result.workflow_name}' completed successfully.")
+                print(f"   Steps executed: {len(result.step_results)}")
+                for name, uri_out in output_uris.items():
+                    print(f"   Terminal Output [{name}]: {uri_out}")
+                for step_id, r_uri in receipt_uris.items():
+                    print(f"   Step [{step_id}] VCard: {r_uri}")
+                wall_ms = result.metrics.get("wall_time_ms", 0.0)
+                print(f"   Total pipeline time: {wall_ms:.2f}ms")
+            return 0
+        else:
+            if as_json:
+                print(
+                    json.dumps(
+                        {
+                            "status": "failed",
+                            "workflow": result.workflow_name,
+                            "failed_step": result.failed_step,
+                            "error": result.error,
+                        },
+                        indent=2,
+                    )
+                )
+            else:
+                print(
+                    f"❌ Workflow '{result.workflow_name}' failed at step '{result.failed_step}': {result.error}"
+                )
+            return 1
+
+    except Exception as e:
+        if as_json:
+            print(json.dumps({"status": "error", "error": str(e)}))
+        else:
+            print(f"❌ Workflow execution exception: {e}")
+        return 1
+
+
+# ── Top-Level Subcommand Handlers ────────────────────────────────────
+
+
+def handle_action_cli(args: list[str], fs: MCardFileSystem | None = None) -> int:
+    """Entry point for `clm action ...` subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="clm action",
+        description="CLM Algebraic Action Operations (Sprint 396 / DEL-396-01)",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand", help="Action operation")
+
+    # validate
+    validate_p = subparsers.add_parser(
+        "validate", help="Statically validate an Action manifest"
+    )
+    validate_p.add_argument("path", help="Path to action.yaml or action.json")
+    validate_p.add_argument(
+        "--json", action="store_true", help="Output validation result as JSON"
+    )
+
+    # run
+    run_p = subparsers.add_parser(
+        "run", help="Execute an Action manifest inside Hoare Sandwich"
+    )
+    run_p.add_argument("path", help="Path to action.yaml or action.json")
+    run_p.add_argument(
+        "--input", "-i", default=None, help="Input MCard URI or local file path"
+    )
+    run_p.add_argument(
+        "--bind",
+        "-b",
+        action="append",
+        dest="bindings",
+        help="Input binding in key=value format (repeatable)",
+    )
+    run_p.add_argument(
+        "--output-handle", "-o", default=None, help="Optional output handle name"
+    )
+    run_p.add_argument("--json", action="store_true", help="Output result as JSON")
+    run_p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Validate and resolve inputs without running operator",
+    )
+
+    # list
+    list_p = subparsers.add_parser(
+        "list", help="List exemplar actions in the canonical catalog"
+    )
+    list_p.add_argument(
+        "--catalog-dir", default=None, help="Custom catalog directory path"
+    )
+    list_p.add_argument("--json", action="store_true", help="Output list as JSON")
+
+    parsed = parser.parse_args(args)
+
+    if parsed.subcommand == "validate":
+        return action_validate_cmd(parsed.path, as_json=parsed.json)
+    elif parsed.subcommand == "run":
+        return action_run_cmd(
+            parsed.path,
+            input_uri=parsed.input,
+            bindings=parsed.bindings,
+            output_handle=parsed.output_handle,
+            as_json=parsed.json,
+            dry_run=parsed.dry_run,
+            fs=fs,
+        )
+    elif parsed.subcommand == "list":
+        return action_list_cmd(catalog_dir=parsed.catalog_dir, as_json=parsed.json)
+    else:
+        parser.print_help()
+        return 1
+
+
+def handle_workflow_cli(args: list[str], fs: MCardFileSystem | None = None) -> int:
+    """Entry point for `clm workflow ...` subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="clm workflow",
+        description="CLM Pocket Flow Workflow Orchestration (Sprint 396 / DEL-396-01)",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand", help="Workflow operation")
+
+    # validate
+    validate_p = subparsers.add_parser(
+        "validate", help="Statically validate a Workflow manifest"
+    )
+    validate_p.add_argument("path", help="Path to workflow.yaml or workflow.json")
+    validate_p.add_argument(
+        "--json", action="store_true", help="Output validation result as JSON"
+    )
+
+    # run
+    run_p = subparsers.add_parser("run", help="Execute a multi-step workflow DAG")
+    run_p.add_argument("path", help="Path to workflow.yaml or workflow.json")
+    run_p.add_argument(
+        "--bind",
+        "-b",
+        action="append",
+        dest="bindings",
+        help="Initial input binding in key=value format (repeatable)",
+    )
+    run_p.add_argument(
+        "--workers",
+        "-w",
+        type=int,
+        default=4,
+        help="Maximum concurrent worker threads for parallel stages",
+    )
+    run_p.add_argument("--json", action="store_true", help="Output result as JSON")
+
+    parsed = parser.parse_args(args)
+
+    if parsed.subcommand == "validate":
+        return workflow_validate_cmd(parsed.path, as_json=parsed.json)
+    elif parsed.subcommand == "run":
+        return workflow_run_cmd(
+            parsed.path,
+            bindings=parsed.bindings,
+            as_json=parsed.json,
+            fs=fs,
+            max_workers=parsed.workers,
+        )
+    else:
+        parser.print_help()
+        return 1