hexaqueue-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{hexaqueue_cli-0.1.0 → hexaqueue_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexaqueue-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: Hexaqueue CLI - Modern developer and operator terminal interface
 Author: Richard West
 Author-email: Richard West <dopplereffect.us@gmail.com>
@@ -8,10 +8,11 @@ License-Expression: Apache-2.0
 Requires-Dist: hexaqueue-core
 Requires-Dist: hexaqueue-server
 Requires-Dist: hexaqueue-worker
-Requires-Dist: hexastack-cli>=0.3.0
-Requires-Dist: hexastack-core>=0.3.0
-Requires-Dist: hexastack-cqrs>=0.3.0
-Requires-Dist: hexastack-grpc>=0.3.0
+Requires-Dist: hexaqueue-workflow
+Requires-Dist: hexastack-cli>=0.6.0
+Requires-Dist: hexastack-core>=0.6.0
+Requires-Dist: hexastack-cqrs>=0.6.0
+Requires-Dist: hexastack-grpc>=0.6.0
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: rich>=13.8.0
 Requires-Dist: typer>=0.15.0

{hexaqueue_cli-0.1.0 → hexaqueue_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hexaqueue-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "Hexaqueue CLI - Modern developer and operator terminal interface"
 readme = "README.md"
 license = "Apache-2.0"
@@ -9,10 +9,11 @@ dependencies = [
     "hexaqueue-core",
     "hexaqueue-server",
     "hexaqueue-worker",
-    "hexastack-cli>=0.3.0",
-    "hexastack-core>=0.3.0",
-    "hexastack-cqrs>=0.3.0",
-    "hexastack-grpc>=0.3.0",
+    "hexaqueue-workflow",
+    "hexastack-cli>=0.6.0",
+    "hexastack-core>=0.6.0",
+    "hexastack-cqrs>=0.6.0",
+    "hexastack-grpc>=0.6.0",
     "pyyaml>=6.0.2",
     "rich>=13.8.0",
     "typer>=0.15.0",
@@ -37,3 +38,6 @@ workspace = true
 
 [tool.uv.sources.hexaqueue-worker]
 workspace = true
+
+[tool.uv.sources.hexaqueue-workflow]
+workspace = true

{hexaqueue_cli-0.1.0 → hexaqueue_cli-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "hexaqueue-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "Hexaqueue CLI - Modern developer and operator terminal interface"
 readme = "README.md"
 license = "Apache-2.0"
@@ -12,10 +12,11 @@ dependencies = [
     "hexaqueue-core",
     "hexaqueue-server",
     "hexaqueue-worker",
-    "hexastack-cli>=0.3.0",
-    "hexastack-core>=0.3.0",
-    "hexastack-cqrs>=0.3.0",
-    "hexastack-grpc>=0.3.0",
+    "hexaqueue-workflow",
+    "hexastack-cli>=0.6.0",
+    "hexastack-core>=0.6.0",
+    "hexastack-cqrs>=0.6.0",
+    "hexastack-grpc>=0.6.0",
     "pyyaml>=6.0.2",
     "rich>=13.8.0",
     "typer>=0.15.0",
@@ -32,3 +33,4 @@ build-backend = "uv_build"
 hexaqueue-core = { workspace = true }
 hexaqueue-server = { workspace = true }
 hexaqueue-worker = { workspace = true }
+hexaqueue-workflow = { workspace = true }

{hexaqueue_cli-0.1.0 → hexaqueue_cli-0.3.0}/src/hexaqueue_cli/adapters/__init__.py

@@ -1,7 +1,7 @@
-"""Adapters package for hexaqueue-cli."""
-
 from hexaqueue_cli.adapters.local import LocalClientAdapter
+from hexaqueue_cli.adapters.presenter import CliPresenter
 
 __all__ = [
+    "CliPresenter",
     "LocalClientAdapter",
 ]

hexaqueue_cli-0.3.0/src/hexaqueue_cli/adapters/presenter.py

@@ -0,0 +1,371 @@
+"""Terminal and pipeline output presenters for Hexaqueue CLI commands.
+
+Notes/Architectural Intent:
+    Provides formatted output rendering across multiple formats (table, json, markdown, plain, rich).
+    Ensures seamless piping into downstream Unix utilities when non-interactive, while
+    delivering rich visual dashboards for human terminal operators.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+from pydantic import BaseModel
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from hexaqueue_cli.domain.options import OutputFormat
+from hexaqueue_core.domain.job import JobSpec
+from hexaqueue_server.domain.models import RunStatusReport
+
+__all__ = [
+    "CliPresenter",
+]
+
+
+class CliPresenter:
+    """Presenter formatting CLI models and reports across supported output formats.
+
+    Notes/Architectural Intent:
+        Implements rendering for table, json, markdown, plain, and rich.
+        Allows commands to dispatch results cleanly without mixing presentation logic
+        with orchestration.
+    """
+
+    def __init__(
+        self,
+        console: Console | None = None,
+        stderr_console: Console | None = None,
+    ) -> None:
+        """Initialize CliPresenter with optional consoles.
+
+        Args:
+            console: Optional Rich console for stdout.
+            stderr_console: Optional Rich console for stderr.
+        """
+        no_color = bool(os.environ.get("NO_COLOR"))
+        self._console = console or Console(no_color=no_color, highlight=not no_color)
+        self._stderr = stderr_console or Console(
+            stderr=True, no_color=no_color, highlight=not no_color
+        )
+
+    def render_run_status(
+        self,
+        report: RunStatusReport,
+        format_type: str | OutputFormat = OutputFormat.TABLE,
+    ) -> None:
+        """Render a pipeline run status report in the chosen format.
+
+        Args:
+            report: RunStatusReport domain model.
+            format_type: Chosen output format string or OutputFormat enum.
+        """
+        fmt = (
+            format_type.value
+            if isinstance(format_type, OutputFormat)
+            else str(format_type).lower().strip()
+        )
+
+        data = {
+            "run_id": report.run_id,
+            "state": (
+                report.state.value
+                if hasattr(report.state, "value")
+                else str(report.state)
+            ),
+            "outcome": (
+                report.outcome.value
+                if hasattr(report.outcome, "value")
+                else (str(report.outcome) if report.outcome else None)
+            ),
+            "total_jobs": report.total_jobs,
+            "completed_jobs": report.completed_jobs,
+            "failed_jobs": report.failed_jobs,
+            "pending_jobs": report.pending_jobs,
+        }
+
+        if fmt == OutputFormat.JSON.value:
+            sys.stdout.write(json.dumps(data, indent=2) + "\n")
+            sys.stdout.flush()
+        elif fmt == OutputFormat.MARKDOWN.value:
+            lines = [
+                f"### Run Status: {report.run_id}",
+                "",
+                "| Field | Value |",
+                "|---|---|",
+                f"| Run ID | `{report.run_id}` |",
+                f"| State | **{data['state']}** |",
+                f"| Outcome | {data['outcome'] or '-'} |",
+                f"| Total Jobs | {report.total_jobs} |",
+                f"| Completed | {report.completed_jobs} |",
+                f"| Failed | {report.failed_jobs} |",
+                f"| Pending | {report.pending_jobs} |",
+            ]
+            sys.stdout.write("\n".join(lines) + "\n")
+            sys.stdout.flush()
+        elif fmt == OutputFormat.PLAIN.value:
+            for k, v in data.items():
+                sys.stdout.write(f"{k}\t{v}\n")
+            sys.stdout.flush()
+        else:
+            # table or rich
+            table = Table(title=f"Run Status: {report.run_id}")
+            table.add_column("Run ID", style="cyan")
+            table.add_column("State", style="magenta")
+            table.add_column(
+                "Outcome",
+                style="green"
+                if str(report.outcome) in ("COMPLETED", "SUCCEEDED")
+                else "yellow",
+            )
+            table.add_column("Total", justify="center")
+            table.add_column("Completed", justify="center", style="green")
+            table.add_column("Failed", justify="center", style="red")
+            table.add_column("Pending", justify="center", style="yellow")
+            table.add_row(
+                report.run_id,
+                data["state"],
+                str(report.outcome) if report.outcome else "-",
+                str(report.total_jobs),
+                str(report.completed_jobs),
+                str(report.failed_jobs),
+                str(report.pending_jobs),
+            )
+            self._console.print(table)
+
+    def render_job(
+        self,
+        job: JobSpec,
+        format_type: str | OutputFormat = OutputFormat.TABLE,
+    ) -> None:
+        """Render a single JobSpec in the chosen format.
+
+        Args:
+            job: JobSpec domain model.
+            format_type: Chosen output format string or OutputFormat enum.
+        """
+        fmt = (
+            format_type.value
+            if isinstance(format_type, OutputFormat)
+            else str(format_type).lower().strip()
+        )
+
+        state_val = job.state.value if hasattr(job.state, "value") else str(job.state)
+        outcome_val = (
+            job.outcome.value
+            if hasattr(job.outcome, "value")
+            else (str(job.outcome) if job.outcome else None)
+        )
+
+        data = {
+            "id": job.id,
+            "run_id": job.run_id,
+            "name": job.name,
+            "state": state_val,
+            "outcome": outcome_val,
+            "command": job.command,
+        }
+
+        if fmt == OutputFormat.JSON.value:
+            sys.stdout.write(json.dumps(data, indent=2) + "\n")
+            sys.stdout.flush()
+        elif fmt == OutputFormat.MARKDOWN.value:
+            lines = [
+                f"### Job Status: {job.id}",
+                "",
+                "| Field | Value |",
+                "|---|---|",
+                f"| Job ID | `{job.id}` |",
+                f"| Run ID | `{job.run_id}` |",
+                f"| Name | {job.name} |",
+                f"| State | **{state_val}** |",
+                f"| Outcome | {outcome_val or '-'} |",
+                f"| Command | `{job.command}` |",
+            ]
+            sys.stdout.write("\n".join(lines) + "\n")
+            sys.stdout.flush()
+        elif fmt == OutputFormat.PLAIN.value:
+            for k, v in data.items():
+                sys.stdout.write(f"{k}\t{v}\n")
+            sys.stdout.flush()
+        else:
+            table = Table(title=f"Job Status: {job.id}")
+            table.add_column("Job ID", style="cyan")
+            table.add_column("Run ID", style="blue")
+            table.add_column("Name")
+            table.add_column("State", style="magenta")
+            table.add_column("Outcome")
+            table.add_row(
+                job.id,
+                job.run_id,
+                job.name,
+                state_val,
+                str(job.outcome) if job.outcome else "-",
+            )
+            self._console.print(table)
+
+    def _serialize_checkpoints(self, checkpoints: list[Any]) -> list[dict[str, Any]]:
+        """Extract serialized dictionary representations of step checkpoints."""
+        chk_list: list[dict[str, Any]] = []
+        for chk in checkpoints:
+            chk_status = (
+                chk.status.value if hasattr(chk.status, "value") else str(chk.status)
+            )
+            payload = (
+                chk.output_payload
+                if not isinstance(chk.output_payload, BaseModel)
+                else chk.output_payload.model_dump()
+            )
+            chk_list.append(
+                {
+                    "stage_name": chk.stage_name,
+                    "step_name": chk.step_name,
+                    "status": chk_status,
+                    "attempt_number": chk.attempt_number,
+                    "duration_seconds": round(chk.duration_seconds, 3),
+                    "output_payload": payload,
+                }
+            )
+        return chk_list
+
+    def _render_workflow_json(self, data: dict[str, Any]) -> None:
+        """Output workflow status report as indented JSON."""
+        sys.stdout.write(json.dumps(data, indent=2, default=str) + "\n")
+        sys.stdout.flush()
+
+    def _render_workflow_markdown(self, data: dict[str, Any]) -> None:
+        """Output workflow status report as Markdown."""
+        lines = [
+            f"### Workflow Run: {data['workflow_name']} (`{data['run_id']}`)",
+            "",
+            f"- **Status**: `{data['status']}`",
+        ]
+        if data.get("current_stage"):
+            lines.append(f"- **Current Stage**: {data['current_stage']}")
+        if data.get("error_summary"):
+            lines.append(f"- **Error**: {data['error_summary']}")
+        lines.extend(
+            [
+                "",
+                "| Stage | Step | Status | Attempt | Duration (s) |",
+                "|---|---|---|---|---|",
+            ]
+        )
+        for c in data.get("checkpoints", []):
+            lines.append(
+                f"| {c['stage_name']} | {c['step_name']} | {c['status']} | {c['attempt_number']} | {c['duration_seconds']} |"
+            )
+        sys.stdout.write("\n".join(lines) + "\n")
+        sys.stdout.flush()
+
+    def _render_workflow_plain(self, data: dict[str, Any]) -> None:
+        """Output workflow status report as plain tab-delimited text."""
+        sys.stdout.write(f"run_id\t{data['run_id']}\n")
+        sys.stdout.write(f"workflow\t{data['workflow_name']}\n")
+        sys.stdout.write(f"status\t{data['status']}\n")
+        for c in data.get("checkpoints", []):
+            sys.stdout.write(
+                f"{c['stage_name']}\t{c['step_name']}\t{c['status']}\t{c['duration_seconds']}\n"
+            )
+        sys.stdout.flush()
+
+    def _render_workflow_table(self, data: dict[str, Any]) -> None:
+        """Output workflow status report as interactive Rich table and panel."""
+        header_table = Table.grid(padding=(0, 2))
+        header_table.add_column(style="bold")
+        header_table.add_column()
+        header_table.add_row("Run ID:", str(data["run_id"]))
+        header_table.add_row("Workflow:", str(data["workflow_name"]))
+        header_table.add_row("Status:", f"[bold cyan]{data['status']}[/]")
+        if data.get("current_stage"):
+            header_table.add_row("Current Stage:", str(data["current_stage"]))
+        if data.get("error_summary"):
+            header_table.add_row("Error:", f"[bold red]{data['error_summary']}[/]")
+
+        self._console.print(
+            Panel(
+                header_table,
+                title=f"Workflow Run: {data['workflow_name']}",
+                expand=False,
+            )
+        )
+
+        chk_list = data.get("checkpoints", [])
+        if not chk_list:
+            self._console.print("[dim]No step checkpoints recorded yet.[/]")
+            return
+
+        table = Table(title="Step Checkpoints & Staged Artifacts", expand=True)
+        table.add_column("Stage", style="cyan")
+        table.add_column("Step", style="bold")
+        table.add_column("Status", justify="center")
+        table.add_column("Attempt", justify="right")
+        table.add_column("Duration (s)", justify="right")
+        table.add_column("Artifact / Output", style="dim")
+
+        for chk in chk_list:
+            chk_color = (
+                "[green]COMPLETED[/]"
+                if chk["status"] == "COMPLETED"
+                else (
+                    "[red]FAILED[/]"
+                    if chk["status"] == "FAILED"
+                    else str(chk["status"])
+                )
+            )
+            payload_repr = str(chk["output_payload"])
+            if len(payload_repr) > 30:
+                payload_repr = payload_repr[:30] + "..."
+
+            table.add_row(
+                chk["stage_name"],
+                chk["step_name"],
+                chk_color,
+                str(chk["attempt_number"]),
+                f"{chk['duration_seconds']:.3f}",
+                payload_repr,
+            )
+        self._console.print(table)
+
+    def render_workflow_state(
+        self,
+        state: Any,
+        checkpoints: list[Any],
+        format_type: str | OutputFormat = OutputFormat.TABLE,
+    ) -> None:
+        """Render workflow execution state and checkpoints in the chosen format.
+
+        Args:
+            state: WorkflowExecutionState instance.
+            checkpoints: List of CheckpointRecord instances.
+            format_type: Chosen output format string or OutputFormat enum.
+        """
+        fmt = (
+            format_type.value
+            if isinstance(format_type, OutputFormat)
+            else str(format_type).lower().strip()
+        )
+        status_val = (
+            state.status.value if hasattr(state.status, "value") else str(state.status)
+        )
+        data = {
+            "run_id": state.run_id,
+            "workflow_name": state.workflow_name,
+            "status": status_val,
+            "current_stage": getattr(state, "current_stage", None),
+            "error_summary": getattr(state, "error_summary", None),
+            "checkpoints": self._serialize_checkpoints(checkpoints),
+        }
+
+        if fmt == OutputFormat.JSON.value:
+            self._render_workflow_json(data)
+        elif fmt == OutputFormat.MARKDOWN.value:
+            self._render_workflow_markdown(data)
+        elif fmt == OutputFormat.PLAIN.value:
+            self._render_workflow_plain(data)
+        else:
+            self._render_workflow_table(data)

hexaqueue_cli-0.3.0/src/hexaqueue_cli/commands/__init__.py

@@ -0,0 +1,13 @@
+"""Commands package for hexaqueue-cli.
+
+Notes/Architectural Intent:
+    Exposes Typer subcommand modules for batch run pipelines and distributed workflow execution.
+"""
+
+from hexaqueue_cli.commands.run import app as run_app
+from hexaqueue_cli.commands.workflow import app as workflow_app
+
+__all__ = [
+    "run_app",
+    "workflow_app",
+]

{hexaqueue_cli-0.1.0 → hexaqueue_cli-0.3.0}/src/hexaqueue_cli/commands/run.py

@@ -10,11 +10,12 @@ from pathlib import Path
 
 import typer
 from rich.console import Console
-from rich.table import Table
 
 from hexaqueue_cli.adapters.local import LocalClientAdapter
+from hexaqueue_cli.adapters.presenter import CliPresenter
 from hexaqueue_cli.domain.parser import parse_run_spec_from_file
 from hexaqueue_cli.domain.session import get_default_session
+from hexaqueue_cli.infra.options import format_option, resolve_format
 from hexaqueue_core.domain.lifecycle import RunState
 
 app = typer.Typer(help="Pipeline run management commands.")
@@ -27,6 +28,7 @@ def submit_cmd(
     watch: bool = typer.Option(
         False, "--watch", "-w", help="Watch run execution until completion"
     ),
+    format_type: str = format_option(),
 ) -> None:
     """Submit a DAG pipeline definition file."""
     try:
@@ -35,41 +37,38 @@ def submit_cmd(
         console.print(f"[bold red]Error parsing pipeline spec:[/] {e}")
         raise typer.Exit(code=1) from e
 
+    resolved_fmt = resolve_format(format_type)
+    presenter = CliPresenter(console=console)
+
     async def _run() -> None:
         session = get_default_session()
         await session.start()
         client = LocalClientAdapter(session=session)
 
         report = await client.submit_run(submission)
-        console.print(
-            f"[bold green]✓[/] Run '[bold cyan]{report.run_id}[/]' submitted ({report.total_jobs} jobs)"
-        )
+        if resolved_fmt in ("table", "rich"):
+            console.print(
+                f"[bold green]✓[/] Run '[bold cyan]{report.run_id}[/]' submitted ({report.total_jobs} jobs)"
+            )
+        else:
+            presenter.render_run_status(report, resolved_fmt)
+
+        if not watch:
+            return
 
-        if watch:
-            with console.status(f"[bold blue]Executing run {report.run_id}...[/]"):
-                while report.state not in (RunState.DONE, RunState.BLOCKED):
-                    await asyncio.sleep(0.1)
-                    report = await client.get_run_status(report.run_id)
+        with console.status(f"[bold blue]Executing run {report.run_id}...[/]"):
+            while report.state not in (RunState.DONE, RunState.BLOCKED):
+                await asyncio.sleep(0.1)
+                report = await client.get_run_status(report.run_id)
 
+        if resolved_fmt in ("table", "rich"):
             outcome_str = (
                 f"[bold green]{report.outcome}[/]"
-                if report.outcome == "COMPLETED" or report.outcome == "SUCCEEDED"
+                if str(report.outcome) in ("COMPLETED", "SUCCEEDED")
                 else f"[bold red]{report.outcome}[/]"
             )
             console.print(f"Run completed with status: {outcome_str}")
-
-            table = Table(title=f"Run Summary: {report.run_id}")
-            table.add_column("Total", justify="center")
-            table.add_column("Completed", justify="center", style="green")
-            table.add_column("Failed", justify="center", style="red")
-            table.add_column("Pending", justify="center", style="yellow")
-            table.add_row(
-                str(report.total_jobs),
-                str(report.completed_jobs),
-                str(report.failed_jobs),
-                str(report.pending_jobs),
-            )
-            console.print(table)
+        presenter.render_run_status(report, resolved_fmt)
 
     asyncio.run(_run())
 

hexaqueue_cli-0.3.0/src/hexaqueue_cli/commands/workflow.py

@@ -0,0 +1,298 @@
+"""CLI commands for Hexaflow distributed workflow management in Hexaqueue.
+
+Notes/Architectural Intent:
+    Provides subcommands for submitting workflow DAG definitions to the cluster,
+    inspecting step checkpoints and staged artifact URIs, resuming suspended workflows,
+    and aborting active workflows with reverse compensation unwinding.
+"""
+
+import asyncio
+import importlib.util
+import json
+from pathlib import Path
+from typing import Any
+
+import typer
+from hexaflow.adapters.storage.sqlite import SqliteStateStore
+from hexaflow.domain.models import WorkflowDefinition
+from hexaflow.dsl.builder import Workflow
+from rich.console import Console
+
+from hexaqueue_cli.adapters.presenter import CliPresenter
+from hexaqueue_cli.infra.options import format_option, resolve_format
+from hexaqueue_workflow.adapters.engines.distributed import HexaqueueDistributedEngine
+
+app = typer.Typer(
+    name="workflow",
+    help="Hexaflow distributed workflow orchestration and cluster scheduling commands.",
+    no_args_is_help=True,
+)
+console = Console()
+presenter = CliPresenter(console=console)
+
+
+def load_workflow_from_target(target: str) -> WorkflowDefinition:
+    """Dynamically load a Workflow or WorkflowDefinition from a file target.
+
+    Supports 'path/to/file.py:workflow_name' or 'path/to/file.py' looking for
+    the 'workflow' variable or an instance of Workflow/WorkflowDefinition.
+
+    Args:
+        target: String path or module identifier (e.g. 'flows/pipeline.py:main_flow').
+
+    Returns:
+        Compiled WorkflowDefinition.
+
+    Raises:
+        typer.BadParameter: If file or workflow variable cannot be loaded.
+
+    Notes/Architectural Intent:
+        Enables seamless loading of user-defined DAG workflows without requiring
+        prior compilation or separate registration steps.
+    """
+    if ":" in target:
+        file_part, attr_name = target.split(":", 1)
+    else:
+        file_part, attr_name = target, None
+
+    file_path = Path(file_part).resolve()
+    if not file_path.exists():
+        msg = f"Workflow file '{file_path}' does not exist"
+        raise typer.BadParameter(msg)
+
+    spec = importlib.util.spec_from_file_location("dynamic_workflow_module", file_path)
+    if not spec or not spec.loader:
+        msg = f"Cannot load Python module from '{file_path}'"
+        raise typer.BadParameter(msg)
+
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    wf_candidate: Any = None
+    if attr_name:
+        if not hasattr(module, attr_name):
+            msg = f"Module '{file_path}' does not define attribute '{attr_name}'"
+            raise typer.BadParameter(msg)
+        wf_candidate = getattr(module, attr_name)
+    else:
+        if hasattr(module, "workflow"):
+            wf_candidate = module.workflow
+        else:
+            for item in vars(module).values():
+                if isinstance(item, (Workflow, WorkflowDefinition)):
+                    wf_candidate = item
+                    break
+
+    if wf_candidate is None:
+        msg = f"No Workflow or WorkflowDefinition instance found in '{file_path}'"
+        raise typer.BadParameter(msg)
+
+    if isinstance(wf_candidate, Workflow):
+        return wf_candidate.compile()
+    if isinstance(wf_candidate, WorkflowDefinition):
+        return wf_candidate
+
+    msg = f"Target object '{wf_candidate}' is not a Workflow or WorkflowDefinition"
+    raise typer.BadParameter(msg)
+
+
+def parse_inputs_arg(inputs: str | None) -> dict[str, Any]:
+    """Parse JSON string or key=val pairs into a dictionary.
+
+    Args:
+        inputs: Raw CLI inputs argument string.
+
+    Returns:
+        Dictionary of input arguments.
+
+    Raises:
+        typer.BadParameter: If JSON decoding fails.
+    """
+    if not inputs:
+        return {}
+    try:
+        parsed = json.loads(inputs)
+        if isinstance(parsed, dict):
+            return parsed
+        msg = "Input JSON must be an object/dict"
+        raise ValueError(msg)
+    except Exception as e:
+        msg = f"Invalid JSON inputs string: {e}"
+        raise typer.BadParameter(msg) from e
+
+
+@app.command("submit")
+def submit_cmd(
+    target: str = typer.Argument(
+        ...,
+        help="Path to workflow file, e.g. 'pipeline.py' or 'pipeline.py:my_flow'",
+    ),
+    inputs: str | None = typer.Option(
+        None, "--inputs", "-i", help="JSON dictionary of initial inputs"
+    ),
+    db_path: str = typer.Option(
+        ".hexaflow/state.db", "--db", help="Path to SQLite state database"
+    ),
+    watch: bool = typer.Option(
+        False, "--watch", "-w", help="Watch workflow execution until completion"
+    ),
+    format_type: str = format_option(),
+) -> None:
+    """Submit a workflow definition for distributed cluster execution.
+
+    Args:
+        target: Target file path or specifier.
+        inputs: Optional JSON inputs string.
+        db_path: SQLite state store database path.
+        watch: Whether to block and watch until terminal completion.
+        format_type: Output presentation format.
+    """
+    workflow = load_workflow_from_target(target)
+    initial_inputs = parse_inputs_arg(inputs)
+    resolved_fmt = resolve_format(format_type)
+
+    store = SqliteStateStore(db_path=db_path)
+    engine = HexaqueueDistributedEngine(state_store=store)
+
+    if resolved_fmt in ("table", "rich"):
+        console.print(
+            f"[bold green]Submitting workflow:[/] [cyan]{workflow.name}[/] "
+            f"({len(workflow.stages)} stages, {sum(len(s.steps) for s in workflow.stages)} steps)"
+        )
+
+    async def _execute() -> None:
+        state = await engine.run_async(workflow, initial_inputs=initial_inputs)
+        _render_workflow_state(state, store, resolved_fmt)
+
+    asyncio.run(_execute())
+
+
+@app.command("status")
+def status_cmd(
+    run_id: str = typer.Argument(
+        ..., help="Workflow execution run identifier to inspect"
+    ),
+    db_path: str = typer.Option(
+        ".hexaflow/state.db", "--db", help="Path to SQLite state database"
+    ),
+    format_type: str = format_option(),
+) -> None:
+    """Inspect status, checkpoints, and staged artifacts for a workflow run.
+
+    Args:
+        run_id: Run identifier to query.
+        db_path: SQLite state store database path.
+        format_type: Output presentation format.
+    """
+    resolved_fmt = resolve_format(format_type)
+    store = SqliteStateStore(db_path=db_path)
+    state = store.get_run(run_id)
+
+    if not state:
+        console.print(
+            f"[bold red]Error:[/] Workflow run '{run_id}' not found in database '{db_path}'."
+        )
+        raise typer.Exit(code=1)
+
+    _render_workflow_state(state, store, resolved_fmt)
+
+
+@app.command("resume")
+def resume_cmd(
+    run_id: str = typer.Argument(..., help="Suspended workflow run identifier"),
+    target: str = typer.Argument(
+        ...,
+        help="Path to workflow file, e.g. 'pipeline.py' or 'pipeline.py:my_flow'",
+    ),
+    inputs: str | None = typer.Option(
+        None, "--inputs", "-i", help="Patch inputs for resuming step frontier"
+    ),
+    skip_steps: list[str] = typer.Option(
+        None, "--skip", help="Step names to explicitly skip"
+    ),
+    db_path: str = typer.Option(
+        ".hexaflow/state.db", "--db", help="Path to SQLite state database"
+    ),
+    format_type: str = format_option(),
+) -> None:
+    """Resume execution of a suspended workflow run from its latest checkpoints.
+
+    Args:
+        run_id: Suspended run identifier.
+        target: Target workflow file specifier.
+        inputs: Optional patch inputs.
+        skip_steps: Optional step names to skip.
+        db_path: SQLite state database path.
+        format_type: Output presentation format.
+    """
+    workflow = load_workflow_from_target(target)
+    patch_inputs = parse_inputs_arg(inputs)
+    resolved_fmt = resolve_format(format_type)
+
+    store = SqliteStateStore(db_path=db_path)
+    engine = HexaqueueDistributedEngine(state_store=store)
+
+    if resolved_fmt in ("table", "rich"):
+        console.print(f"[bold yellow]Resuming workflow run:[/] [cyan]{run_id}[/]")
+
+    async def _resume() -> None:
+        state = await engine.resume_async(
+            run_id=run_id,
+            workflow=workflow,
+            patch_inputs=patch_inputs,
+            skip_steps=set(skip_steps or ()),
+        )
+        _render_workflow_state(state, store, resolved_fmt)
+
+    asyncio.run(_resume())
+
+
+@app.command("abort")
+def abort_cmd(
+    run_id: str = typer.Argument(..., help="Workflow run identifier to abort"),
+    target: str = typer.Argument(..., help="Path to workflow file"),
+    db_path: str = typer.Option(
+        ".hexaflow/state.db", "--db", help="Path to SQLite state database"
+    ),
+    format_type: str = format_option(),
+) -> None:
+    """Abort an active or suspended workflow, unwinding step compensations in reverse order.
+
+    Args:
+        run_id: Run identifier to abort.
+        target: Workflow file specifier containing compensations.
+        db_path: SQLite state database path.
+        format_type: Output presentation format.
+    """
+    workflow = load_workflow_from_target(target)
+    resolved_fmt = resolve_format(format_type)
+    store = SqliteStateStore(db_path=db_path)
+    engine = HexaqueueDistributedEngine(state_store=store)
+
+    if resolved_fmt in ("table", "rich"):
+        console.print(f"[bold red]Aborting workflow run:[/] [cyan]{run_id}[/]")
+
+    async def _abort() -> None:
+        state = await engine.abort_async(run_id=run_id, workflow=workflow)
+        _render_workflow_state(state, store, resolved_fmt)
+
+    asyncio.run(_abort())
+
+
+def _render_workflow_state(
+    state: Any, store: SqliteStateStore, format_type: str = "table"
+) -> None:
+    """Render workflow status summary and step checkpoint table."""
+    checkpoints = store.get_checkpoints(state.run_id)
+    presenter.render_workflow_state(state, checkpoints, format_type=format_type)
+
+
+__all__ = [
+    "abort_cmd",
+    "app",
+    "load_workflow_from_target",
+    "parse_inputs_arg",
+    "resume_cmd",
+    "status_cmd",
+    "submit_cmd",
+]

{hexaqueue_cli-0.1.0 → hexaqueue_cli-0.3.0}/src/hexaqueue_cli/domain/__init__.py

@@ -1,5 +1,6 @@
 """Domain package for hexaqueue-cli."""
 
+from hexaqueue_cli.domain.options import OutputFormat
 from hexaqueue_cli.domain.parser import (
     parse_run_spec_from_dict,
     parse_run_spec_from_file,
@@ -13,6 +14,7 @@ from hexaqueue_cli.domain.session import (
 __all__ = [
     "get_default_session",
     "LocalCliSession",
+    "OutputFormat",
     "parse_run_spec_from_dict",
     "parse_run_spec_from_file",
     "set_default_session",

hexaqueue_cli-0.3.0/src/hexaqueue_cli/domain/options.py

@@ -0,0 +1,25 @@
+"""Domain representations for CLI output presentation formats.
+
+Notes/Architectural Intent:
+    Defines the canonical output format enumeration shared across CLI presenters,
+    command runners, and reporting bridges. Fulfills the cross-ecosystem CLI alignment invariant.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+__all__ = [
+    "OutputFormat",
+]
+
+
+class OutputFormat(StrEnum):
+    """Supported output presentation formats for CLI commands."""
+
+    AUTO = "auto"
+    JSON = "json"
+    MARKDOWN = "markdown"
+    PLAIN = "plain"
+    RICH = "rich"
+    TABLE = "table"

hexaqueue_cli-0.3.0/src/hexaqueue_cli/infra/__init__.py

@@ -0,0 +1,8 @@
+from hexaqueue_cli.infra.bootstrap import CliBootstrapper
+from hexaqueue_cli.infra.options import format_option, resolve_format
+
+__all__ = [
+    "CliBootstrapper",
+    "format_option",
+    "resolve_format",
+]

hexaqueue_cli-0.3.0/src/hexaqueue_cli/infra/options.py

@@ -0,0 +1,73 @@
+"""CLI option factories and formatting resolvers for Hexaqueue CLI applications.
+
+Notes/Architectural Intent:
+    Provides standardized Typer option factories and stdout pipe-detection routines.
+    When format is 'auto', automatically routes to structured JSON when piped into
+    downstream Unix utilities (jq, grep) or styled Rich/table output when attached to an
+    interactive TTY. Aligns with the Hexa ecosystem CLI standards.
+"""
+
+from __future__ import annotations
+
+import sys
+from enum import Enum
+from typing import Any
+
+import typer
+
+from hexaqueue_cli.domain.options import OutputFormat
+
+__all__ = [
+    "format_option",
+    "resolve_format",
+]
+
+
+def resolve_format(
+    format_type: str | OutputFormat,
+    default_tty: str = "table",
+    default_pipe: str = "json",
+) -> str:
+    """Resolve an output format string, handling auto-detection for pipes.
+
+    Args:
+        format_type: The format chosen by user or default ('auto', 'table', 'json', etc.).
+        default_tty: Default format when connected to an interactive terminal.
+        default_pipe: Default format when stdout is piped or redirected.
+
+    Returns:
+        Normalized lowercase format string (e.g. 'table', 'json', 'rich').
+
+    Notes/Architectural Intent:
+        When format_type is 'auto', inspects sys.stdout.isatty() to choose between
+        structured machine-readable format for pipelines or visual format for humans.
+    """
+    raw = (
+        format_type.value
+        if isinstance(format_type, Enum)
+        else str(format_type).lower().strip()
+    )
+    if raw == OutputFormat.AUTO.value:
+        if not sys.stdout.isatty():
+            return default_pipe
+        return default_tty
+    return raw
+
+
+def format_option(
+    default: str = "table",
+    help_text: str = "Output presentation format (table, json, markdown, rich, plain, auto).",
+) -> Any:
+    """Construct a standardized Typer option for format selection.
+
+    Args:
+        default: Default format option value.
+        help_text: Help string to render in CLI usage catalogs.
+
+    Returns:
+        Configured Typer Option specification.
+
+    Notes/Architectural Intent:
+        Standardizes '-f' / '--format' flag across all Hexaqueue CLI commands.
+    """
+    return typer.Option(default, "-f", "--format", help=help_text)

{hexaqueue_cli-0.1.0 → hexaqueue_cli-0.3.0}/src/hexaqueue_cli/main.py

@@ -8,10 +8,12 @@ import asyncio
 
 import typer
 from rich.console import Console
-from rich.table import Table
 
 from hexaqueue_cli.adapters.local import LocalClientAdapter
+from hexaqueue_cli.adapters.presenter import CliPresenter
 from hexaqueue_cli.commands.run import app as run_app
+from hexaqueue_cli.commands.workflow import app as workflow_app
+from hexaqueue_cli.infra.options import format_option, resolve_format
 
 app = typer.Typer(
     name="hq",
@@ -19,6 +21,7 @@ app = typer.Typer(
     no_args_is_help=True,
 )
 app.add_typer(run_app, name="run")
+app.add_typer(workflow_app, name="workflow")
 
 console = Console()
 
@@ -26,58 +29,24 @@ console = Console()
 @app.command("status")
 def status_cmd(
     target_id: str = typer.Argument(..., help="Run ID or Job ID to inspect"),
+    format_type: str = format_option(),
 ) -> None:
     """Check status of a run or job."""
+    resolved_fmt = resolve_format(format_type)
+    presenter = CliPresenter(console=console)
 
     async def _status() -> None:
         client = LocalClientAdapter()
         try:
             report = await client.get_run_status(target_id)
-            table = Table(title=f"Run Status: {report.run_id}")
-            table.add_column("Run ID", style="cyan")
-            table.add_column("State", style="magenta")
-            table.add_column(
-                "Outcome",
-                style="green"
-                if report.outcome in ("COMPLETED", "SUCCEEDED")
-                else "yellow",
-            )
-            table.add_column("Total", justify="center")
-            table.add_column("Completed", justify="center", style="green")
-            table.add_column("Failed", justify="center", style="red")
-            table.add_column("Pending", justify="center", style="yellow")
-            table.add_row(
-                report.run_id,
-                report.state.value
-                if hasattr(report.state, "value")
-                else str(report.state),
-                str(report.outcome) if report.outcome else "-",
-                str(report.total_jobs),
-                str(report.completed_jobs),
-                str(report.failed_jobs),
-                str(report.pending_jobs),
-            )
-            console.print(table)
+            presenter.render_run_status(report, resolved_fmt)
             return
         except Exception:
             pass
 
         try:
             job = await client.get_job(target_id)
-            table = Table(title=f"Job Status: {job.id}")
-            table.add_column("Job ID", style="cyan")
-            table.add_column("Run ID", style="blue")
-            table.add_column("Name")
-            table.add_column("State", style="magenta")
-            table.add_column("Outcome")
-            table.add_row(
-                job.id,
-                job.run_id,
-                job.name,
-                job.state.value if hasattr(job.state, "value") else str(job.state),
-                str(job.outcome) if job.outcome else "-",
-            )
-            console.print(table)
+            presenter.render_job(job, resolved_fmt)
         except Exception as e:
             console.print(f"[bold red]Error querying status for '{target_id}':[/] {e}")
             raise typer.Exit(code=1) from e

hexaqueue_cli-0.1.0/src/hexaqueue_cli/commands/__init__.py

@@ -1,7 +0,0 @@
-"""Commands package for hexaqueue-cli."""
-
-from hexaqueue_cli.commands.run import app as run_app
-
-__all__ = [
-    "run_app",
-]

hexaqueue_cli-0.1.0/src/hexaqueue_cli/infra/__init__.py

@@ -1,7 +0,0 @@
-"""Infra package for hexaqueue-cli."""
-
-from hexaqueue_cli.infra.bootstrap import CliBootstrapper
-
-__all__ = [
-    "CliBootstrapper",
-]