@ngocsangairvds/vsaf 3.2.16 → 4.0.0

package/tools/vds-scripts/scheduler_orchestrator/src/vds_scheduler_orchestrator/cli.py

@@ -1,1112 +0,0 @@
-"""
-cli.py — Typer CLI entry point for the VDS Ecosystem Scheduler.
-
-Entry point: vds-scheduler (see pyproject.toml [project.scripts])
-Integration:  vds-cli registers this as the 'scheduler' subgroup.
-
-Command surface:
-
-  TSK-1.5 (landed — workflow alias registry):
-    vds-scheduler workflows registry list
-    vds-scheduler workflows registry show <alias>
-
-  TSK-6.1 (schedule CRUD + trigger-now) — wired to real Python backends (WP-2):
-    vds-scheduler schedules list
-    vds-scheduler schedules show <name>
-    vds-scheduler schedules create <name> --workflow <fqn> --cron <expr>
-    vds-scheduler schedules pause <name>
-    vds-scheduler schedules resume <name>
-    vds-scheduler schedules trigger-now <name>
-    vds-scheduler schedules delete <name> --yes
-
-  TSK-6.2 (workflows + events) — HTTP stubs until WP-3/WP-4 backends land:
-    vds-scheduler workflows list [--status <s>] [--since <dur>]
-    vds-scheduler workflows show <workflow_id>
-    vds-scheduler workflows replay <workflow_id>
-    vds-scheduler workflows cancel <workflow_id>
-    vds-scheduler events tail [--topic <pattern>] [--since <dur>] [--follow]
-    vds-scheduler events publish <topic> --payload <json>
-
-  TSK-11.9 (Phase 2 — websocket events stream):
-    vds-scheduler events tail --follow  (WS /api/v1/events/stream, live push)
-
-Output defaults:
-  --format json (machine-readable, default for all commands)
-  --format table (Rich table, human-friendly fallback)
-
-Schedule command architecture (WP-2 landed):
-  Schedule CRUD commands call the Python backend directly (same pattern as
-  registry commands). No HTTP round-trip required for read/write operations.
-  DATABASE_URL must be configured.
-
-trigger-now correctness (WAVE-2-GUARDRAILS.md §1):
-  schedules.trigger_now() uses queue.enqueue(workflow_fn, ...) with the
-  schedule's queue_name — NOT DBOS.trigger_schedule(). DBOS must be running
-  (VDS_SCHEDULER_ENABLED=true) for cron mutations and trigger-now.
-"""
-
-from __future__ import annotations
-
-import asyncio as _asyncio
-import json as _json
-import os
-from enum import StrEnum
-
-import httpx
-import typer
-from rich.console import Console
-from rich.table import Table
-
-from vds_scheduler_orchestrator.scheduler.schedules import (
-    ScheduleNotFoundError,
-)
-from vds_scheduler_orchestrator.scheduler.schedules import (
-    get as _sched_get,
-)
-from vds_scheduler_orchestrator.scheduler.schedules import (
-    list_schedules as _sched_list,
-)
-
-# v2.0.16 cleanup: removed dead imports from v2.0.14 N.29 CLI HTTP migration —
-# create/delete/pause/resume/trigger_now/OverlapPolicy/DuplicateScheduleError/
-# InvalidCronExprError/UnknownQueueError were imported but never called from
-# the CLI body (HTTP-mediated path uses _call_service exclusively). Read-side
-# get + list_schedules retained for direct-DB reads where appropriate.
-from vds_scheduler_orchestrator.workflows.queues import KNOWN_QUEUE_NAMES
-from vds_scheduler_orchestrator.workflows.registry import (
-    AliasNotFoundError,
-    get_alias,
-    list_aliases,
-)
-
-console = Console()
-err_console = Console(stderr=True)
-
-# ── Output format ─────────────────────────────────────────────────────────────
-
-
-class OutputFormat(StrEnum):
-    JSON = "json"
-    TABLE = "table"
-
-
-# ── Output helpers ────────────────────────────────────────────────────────────
-
-
-def _print_json(data: object) -> None:
-    """
-    Print data as JSON to stdout.
-
-    Uses plain print() with compact JSON (not Rich's print_json) so that
-    the output is reliably parseable by json.loads() without ANSI codes,
-    Rich markup, or extra whitespace that non-TTY Rich output can emit.
-    Human-friendly pretty printing is done via --format table instead.
-    """
-    print(_json.dumps(data))
-
-
-def _call_service(
-    method: str,
-    path: str,
-    base_url: str,
-    *,
-    json_body: dict | None = None,
-    params: dict | None = None,
-) -> object:
-    """
-    Make a synchronous HTTP call to the scheduler service.
-
-    On connection error, timeout, or HTTP 4xx/5xx: prints a human-readable
-    error to stderr and raises typer.Exit(1).
-
-    Returns:
-        Parsed JSON response body (dict or list).
-    """
-    headers: dict[str, str] = {"Accept": "application/json"}
-    api_key = os.environ.get("VDS_SCHEDULER_API_KEY")
-    if api_key:
-        headers["X-VDS-Scheduler-Key"] = api_key
-    # v2.0.18: auto-attach X-Capability so mutation routes (per ADR-22/24) get a
-    # real capability instead of falling back to the API default 'guest' (HTTP 403
-    # on delete/pause/resume/etc). Read at call time — same constant-time, no-cache
-    # pattern as the API key above.
-    capability = os.environ.get("VDS_SCHEDULER_CAPABILITY")
-    if capability:
-        headers["X-Capability"] = capability
-
-    try:
-        with httpx.Client(
-            base_url=base_url.rstrip("/"),
-            timeout=30.0,
-            headers=headers,
-        ) as client:
-            resp = client.request(method, path, json=json_body, params=params)
-            resp.raise_for_status()
-            # v2.0.14 TSK-N.29: 204 No Content (e.g. DELETE) and other empty
-            # responses must not be JSON-parsed — return None so callers can
-            # treat the call as a success-with-no-body.
-            if resp.status_code == 204 or not resp.content:
-                return None
-            return resp.json()
-    except httpx.ConnectError:
-        err_console.print(
-            f"[red]Cannot connect to scheduler service at {base_url}[/red]\n"
-            "[dim]Set VDS_SCHEDULER_BASE_URL env var or pass --scheduler-url[/dim]"
-        )
-        raise typer.Exit(1)
-    except httpx.TimeoutException:
-        err_console.print(f"[red]Request timed out connecting to {base_url}[/red]")
-        raise typer.Exit(1)
-    except httpx.HTTPStatusError as exc:
-        try:
-            body = exc.response.json()
-        except Exception:
-            body = exc.response.text
-        err_console.print(f"[red]HTTP {exc.response.status_code}:[/red] {body}")
-        raise Exception
-
-
-# ── Shared constants ──────────────────────────────────────────────────────────
-
-_SCHEDULER_URL_ENV = "VDS_SCHEDULER_BASE_URL"
-# Default port matches DEPLOYMENT-RUNBOOK.md Stage 3 + scheduler_orchestrator/README.md
-# (uvicorn binds 127.0.0.1:8005 on local rollout; production uses VDS_SCHEDULER_BASE_URL).
-# v2.0.13 TSK-N.20: changed from :8000 → :8005 to reconcile CLI default with runbook.
-_DEFAULT_URL = "http://localhost:8005"
-_FORMAT_HELP = "Output format: json (default, machine-readable) | table (Rich table)"
-
-
-# ── Typer application ─────────────────────────────────────────────────────────
-
-app = typer.Typer(
-    name="scheduler",
-    help="VDS Ecosystem Scheduler — manage schedules, events, chains, and workflows.",
-    no_args_is_help=True,
-)
-
-# ── Sub-groups ────────────────────────────────────────────────────────────────
-
-schedules_app = typer.Typer(help="Manage cron/interval/one-shot schedules.", no_args_is_help=True)
-workflows_app = typer.Typer(help="List, trigger, and manage durable workflows.", no_args_is_help=True)
-registry_app = typer.Typer(help="Workflow alias registry — list and inspect registrations.", no_args_is_help=True)
-events_app = typer.Typer(help="Publish and tail event topics.", no_args_is_help=True)
-chains_app = typer.Typer(help="Manage chain definitions and fire logs.", no_args_is_help=True)
-
-app.add_typer(schedules_app, name="schedules")
-app.add_typer(workflows_app, name="workflows")
-app.add_typer(events_app, name="events")
-app.add_typer(chains_app, name="chains")
-workflows_app.add_typer(registry_app, name="registry")
-
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# TSK-1.5: Workflow alias registry (landed in Wave 1)
-# ═══════════════════════════════════════════════════════════════════════════════
-
-
-@registry_app.command("list")
-def registry_list(
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-) -> None:
-    """
-    List all registered workflow aliases.
-
-    Shows alias, FQN, owner orchestrator, version, and last_resolved_at.
-    """
-    try:
-        rows = list_aliases()
-    except Exception as exc:
-        err_console.print(f"[red]Error listing registry: {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    if not rows:
-        _print_json([]) if fmt == OutputFormat.JSON else console.print("[yellow]No workflows registered yet.[/yellow]")
-        return
-
-    if fmt == OutputFormat.JSON:
-        _print_json(
-            [
-                {
-                    "alias": r.alias,
-                    "workflow_fqn": r.workflow_fqn,
-                    "owner_orchestrator": r.owner_orchestrator,
-                    "version": r.version,
-                    "last_resolved_at": str(r.last_resolved_at) if r.last_resolved_at else None,
-                }
-                for r in rows
-            ]
-        )
-        return
-
-    table = Table(title="Workflow Registry", show_lines=True)
-    table.add_column("Alias", style="cyan", no_wrap=True)
-    table.add_column("FQN", style="green")
-    table.add_column("Owner Orchestrator", style="magenta")
-    table.add_column("Version", style="blue")
-    table.add_column("Last Resolved", style="dim")
-    for row in rows:
-        table.add_row(
-            row.alias,
-            row.workflow_fqn,
-            row.owner_orchestrator,
-            row.version,
-            str(row.last_resolved_at) if row.last_resolved_at else "—",
-        )
-    console.print(table)
-
-
-@registry_app.command("show")
-def registry_show(
-    alias: str = typer.Argument(..., help="Workflow alias to look up"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-) -> None:
-    """Show details for a single registered workflow alias."""
-    try:
-        row = get_alias(alias)
-    except AliasNotFoundError as exc:
-        err_console.print(f"[red]{exc}[/red]")
-        raise typer.Exit(1) from exc
-    except Exception as exc:
-        err_console.print(f"[red]Error fetching alias: {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    data = {
-        "alias": row.alias,
-        "workflow_fqn": row.workflow_fqn,
-        "owner_orchestrator": row.owner_orchestrator,
-        "version": row.version,
-        "registered_at": str(row.registered_at),
-        "last_resolved_at": str(row.last_resolved_at) if row.last_resolved_at else None,
-    }
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-        return
-    for k, v in data.items():
-        console.print(f"[bold]{k.replace('_', ' ').title()}:[/bold]  {v or '—'}")
-
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# TSK-6.1: Schedule CRUD + trigger-now
-# ═══════════════════════════════════════════════════════════════════════════════
-
-
-@schedules_app.command("list")
-def schedules_list(
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-) -> None:
-    """
-    List all configured schedules (cron, interval, one-shot).
-
-    Reads directly from sched.schedules via the WP-2 backend (no HTTP required).
-    DATABASE_URL must be set.
-    """
-    try:
-        models = _sched_list()
-    except Exception as exc:
-        err_console.print(f"[red]Error listing schedules: {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    if fmt == OutputFormat.JSON:
-        _print_json([m.model_dump() for m in models])
-        return
-
-    if not models:
-        console.print("[yellow]No schedules configured.[/yellow]")
-        return
-
-    table = Table(title="Schedules", show_lines=True)
-    table.add_column("Name", style="cyan", no_wrap=True)
-    table.add_column("Workflow Alias", style="green")
-    table.add_column("Cron / Interval", style="blue")
-    table.add_column("Queue", style="magenta")
-    table.add_column("Status", style="bold")
-    for m in models:
-        trigger = m.cron_expr or (f"every {m.interval_seconds}s" if m.interval_seconds else m.run_at or "?")
-        status_tag = "[red]paused[/red]" if m.status == "paused" else "[green]active[/green]"
-        table.add_row(
-            m.schedule_name,
-            m.workflow_alias,
-            str(trigger),
-            m.queue_name or "ops-default",
-            status_tag,
-        )
-    console.print(table)
-
-
-@schedules_app.command("show")
-def schedules_show(
-    schedule_name: str = typer.Argument(..., help="Schedule name to inspect"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-) -> None:
-    """
-    Show full details for a single schedule.
-
-    Reads directly from sched.schedules via the WP-2 backend (no HTTP required).
-    """
-    try:
-        model = _sched_get(schedule_name)
-    except ScheduleNotFoundError as exc:
-        err_console.print(f"[red]{exc}[/red]")
-        raise typer.Exit(1) from exc
-    except Exception as exc:
-        err_console.print(f"[red]Error fetching schedule: {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    data = model.model_dump()
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-        return
-    for k, v in data.items():
-        console.print(f"[bold]{k.replace('_', ' ').title()}:[/bold]  {v}")
-
-
-@schedules_app.command("create")
-def schedules_create(
-    schedule_name: str = typer.Argument(..., help="Unique schedule name"),
-    workflow: str = typer.Option(..., "--workflow", "-w", help="Workflow alias or FQN"),
-    cron: str | None = typer.Option(None, "--cron", help="Cron expression (e.g. '0 8 * * *')"),
-    interval: int | None = typer.Option(None, "--interval", help="Interval in seconds"),
-    run_at: str | None = typer.Option(None, "--run-at", help="ISO-8601 timestamp for one-shot"),
-    queue: str | None = typer.Option(
-        None,
-        "--queue",
-        "-q",
-        help=f"DBOS queue name. Known queues: {', '.join(sorted(KNOWN_QUEUE_NAMES))}",
-    ),
-    context: str | None = typer.Option(None, "--context", help="JSON workflow context dict"),
-    backfill: bool = typer.Option(False, "--backfill", help="Enable automatic backfill on missed ticks"),
-    overlap_policy: str = typer.Option(
-        "skip",
-        "--overlap",
-        help="Overlap policy: skip | queue | cancel_previous",
-    ),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-) -> None:
-    """
-    Create a new schedule. Exactly one of --cron / --interval / --run-at must be given.
-
-    --queue must be one of the declared queues (ops-default, agent-default,
-    agent-partitioned, chain-fanout). Defaults to ops-default.
-
-    v2.0.14 TSK-N.29: HTTP-mediated by default — POSTs to /api/v1/schedules
-    on the running scheduler service (no DBOS required in CLI process).
-    Validation happens server-side; 409 → DuplicateScheduleError, 400 →
-    InvalidCron/UnknownQueue, 422 → pydantic validation errors.
-    """
-    trigger_count = sum(1 for x in [cron, interval, run_at] if x is not None)
-    if trigger_count != 1:
-        err_console.print("[red]Exactly one of --cron, --interval, or --run-at must be provided.[/red]")
-        raise typer.Exit(1)
-
-    context_dict: dict | None = None
-    if context:
-        try:
-            context_dict = _json.loads(context)
-        except _json.JSONDecodeError as exc:
-            err_console.print(f"[red]Invalid --context JSON: {exc}[/red]")
-            raise typer.Exit(1) from exc
-
-    from vds_scheduler_orchestrator.config import get_config
-
-    owner = get_config().vds_scheduler_capability
-
-    body: dict = {
-        "schedule_name": schedule_name,
-        "owner_orchestrator": owner,
-        "workflow": workflow,
-        "automatic_backfill": backfill,
-        "overlap_policy": overlap_policy,
-    }
-    if cron is not None:
-        body["cron_expr"] = cron
-    if interval is not None:
-        body["interval_seconds"] = interval
-    if run_at is not None:
-        body["run_at"] = run_at
-    if queue:
-        body["queue_name"] = queue
-    else:
-        body["queue_name"] = "ops-default"
-    if context_dict is not None:
-        body["context"] = context_dict
-
-    data = _call_service("POST", "/api/v1/schedules", _DEFAULT_URL, json_body=body)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-    else:
-        console.print(f"[green]✓ Schedule {schedule_name!r} created.[/green]")
-
-
-@schedules_app.command("pause")
-def schedules_pause(
-    schedule_name: str = typer.Argument(..., help="Schedule name to pause"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-) -> None:
-    """
-    Pause a schedule. Paused schedules stop firing until resumed.
-
-    v2.0.14 TSK-N.29: HTTP-mediated — PATCHes /api/v1/schedules/{name}
-    with body {"paused": true}. 404 if schedule not found.
-    """
-    data = _call_service(
-        "PATCH",
-        f"/api/v1/schedules/{schedule_name}",
-        _DEFAULT_URL,
-        json_body={"paused": True},
-    )
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-    else:
-        console.print(f"[yellow]⏸ Schedule {schedule_name!r} paused.[/yellow]")
-
-
-@schedules_app.command("resume")
-def schedules_resume(
-    schedule_name: str = typer.Argument(..., help="Schedule name to resume"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-) -> None:
-    """
-    Resume a paused schedule. The schedule starts firing immediately.
-
-    v2.0.14 TSK-N.29: HTTP-mediated — PATCHes /api/v1/schedules/{name}
-    with body {"paused": false}. 404 if schedule not found.
-    """
-    data = _call_service(
-        "PATCH",
-        f"/api/v1/schedules/{schedule_name}",
-        _DEFAULT_URL,
-        json_body={"paused": False},
-    )
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-    else:
-        console.print(f"[green]▶ Schedule {schedule_name!r} resumed.[/green]")
-
-
-@schedules_app.command("trigger-now")
-def schedules_trigger_now(
-    schedule_name: str = typer.Argument(..., help="Schedule to trigger immediately"),
-    idempotency_key: str | None = typer.Option(
-        None,
-        "--idempotency-key",
-        "-k",
-        help="Optional idempotency key to prevent duplicate enqueues",
-    ),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-) -> None:
-    """
-    Trigger an immediate out-of-band run of SCHEDULE_NAME.
-
-    Uses queue.enqueue(workflow_fn, context_json) with the schedule's queue_name —
-    respecting configured rate limits and concurrency bounds.
-
-    CORRECTNESS (WAVE-2-GUARDRAILS.md §1):
-        Calls schedules.trigger_now() which uses queue.enqueue() — NOT
-        DBOS.trigger_schedule(). DBOS must be running (VDS_SCHEDULER_ENABLED=true).
-
-    Returns the enqueued workflow_id:
-        vds-scheduler workflows show <workflow_id>
-
-    v2.0.14 TSK-N.29: HTTP-mediated — POSTs /api/v1/schedules/{name}:trigger-now.
-    Idempotency-key support deferred to v2.0.15 (the body could carry it but
-    the current API surface doesn't accept query params on this route).
-    """
-    data = _call_service(
-        "POST",
-        f"/api/v1/schedules/{schedule_name}:trigger-now",
-        _DEFAULT_URL,
-    )
-    workflow_id = data.get("workflow_id") if isinstance(data, dict) else None  # type: ignore[union-attr]
-
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-    else:
-        console.print(
-            f"[green]✓ Triggered {schedule_name!r}[/green]\n"
-            f"  workflow_id: [cyan]{workflow_id}[/cyan]\n"
-            f"  [dim]Poll: vds-scheduler workflows show {workflow_id}[/dim]"
-        )
-
-
-@schedules_app.command("delete")
-def schedules_delete(
-    schedule_name: str = typer.Argument(..., help="Schedule name to delete"),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-) -> None:
-    """
-    Delete a schedule.
-
-    v2.0.14 TSK-N.29: HTTP-mediated — DELETEs /api/v1/schedules/{name}.
-    Idempotent per DBOS contract: 204 whether or not the schedule existed
-    (delete_schedule no-ops on missing). Use --yes to skip confirmation.
-    """
-    if not yes:
-        confirmed = typer.confirm(f"Delete schedule {schedule_name!r}?", default=False)
-        if not confirmed:
-            console.print("[yellow]Aborted.[/yellow]")
-            raise typer.Exit(0)
-
-    _call_service(
-        "DELETE",
-        f"/api/v1/schedules/{schedule_name}",
-        _DEFAULT_URL,
-    )
-
-    if fmt == OutputFormat.JSON:
-        _print_json({"schedule_name": schedule_name, "deleted": True})
-    else:
-        console.print(f"[red]✗ Schedule {schedule_name!r} deleted.[/red]")
-
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# TSK-6.2: Workflows list / show / replay / cancel
-# ═══════════════════════════════════════════════════════════════════════════════
-
-
-@workflows_app.command("list")
-def workflows_list(
-    status: str | None = typer.Option(
-        None,
-        "--status",
-        "-s",
-        help="Filter by status: running | completed | failed | all (VDS canonical) OR ENQUEUED | PENDING | SUCCESS | ERROR | CANCELLED | MAX_RECOVERY_ATTEMPTS_EXCEEDED (DBOS vocab). v2.0.14 TSK-N.28: backend accepts both.",
-    ),
-    since: str | None = typer.Option(
-        None,
-        "--since",
-        help="Only show workflows started within this duration (e.g. '24h', '7d', '30m', '60s'). v2.0.14 TSK-N.28: backend now supports this.",
-    ),
-    limit: int = typer.Option(
-        50,
-        "--limit",
-        "-n",
-        help="Max rows returned (1-500). v2.0.14 TSK-N.28: passthrough to backend ?limit=N.",
-    ),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-    scheduler_url: str = typer.Option(
-        None,
-        "--scheduler-url",
-        envvar=_SCHEDULER_URL_ENV,
-        help="Scheduler service base URL",
-    ),
-) -> None:
-    """
-    List in-flight and recent workflows.
-
-    --status accepts VDS canonical names (running | completed | failed | all) which the
-    backend expands to the appropriate DBOS status set:
-      running   → ENQUEUED + PENDING
-      completed → SUCCESS
-      failed    → ERROR + CANCELLED + MAX_RECOVERY_ATTEMPTS_EXCEEDED
-      all       → no filter (same as omitting --status)
-    DBOS vocab (e.g. ENQUEUED) is also accepted and passes through unchanged.
-
-    Backend: GET /api/v1/workflows (v2.0.13 TSK-N.21 + v2.0.14 TSK-N.28)
-    """
-    effective_url = scheduler_url or _DEFAULT_URL
-    params: dict = {"limit": limit}
-    if status:
-        params["status"] = status
-    if since:
-        params["since"] = since
-
-    data = _call_service("GET", "/api/v1/workflows", effective_url, params=params)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-        return
-
-    wf_list = data if isinstance(data, list) else (data or {}).get("workflows", [])  # type: ignore[union-attr]
-    if not wf_list:
-        console.print("[yellow]No workflows found.[/yellow]")
-        return
-
-    table = Table(title="Workflows", show_lines=True)
-    table.add_column("Workflow ID", style="cyan", no_wrap=True)
-    table.add_column("Name / FQN", style="green")
-    table.add_column("Status", style="bold")
-    table.add_column("Queue", style="magenta")
-    table.add_column("Started", style="dim")
-
-    for w in wf_list:  # type: ignore[union-attr]
-        wf_status = w.get("status", "?")
-        colour = _STATUS_COLOURS.get(wf_status, "white")
-        table.add_row(
-            w.get("workflow_id", "?"),
-            w.get("name", w.get("workflow_fqn", "?")),
-            f"[{colour}]{wf_status}[/{colour}]",
-            w.get("queue_name", "?"),
-            w.get("created_at", "?"),
-        )
-    console.print(table)
-
-
-@workflows_app.command("show")
-def workflows_show(
-    workflow_id: str = typer.Argument(..., help="DBOS workflow ID"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-    scheduler_url: str = typer.Option(
-        None,
-        "--scheduler-url",
-        envvar=_SCHEDULER_URL_ENV,
-        help="Scheduler service base URL",
-    ),
-) -> None:
-    """
-    Show full details for a workflow by ID.
-
-    The DBOS workflow_id IS the LangGraph thread_id (ADR-2), so this ID links
-    both the DBOS step timeline and the LangGraph graph checkpoint state.
-
-    Backend: TSK-2.x  GET /api/v1/workflows/{id}
-    """
-    effective_url = scheduler_url or _DEFAULT_URL
-    data = _call_service("GET", f"/api/v1/workflows/{workflow_id}", effective_url)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-        return
-    for k, v in (data or {}).items():  # type: ignore[union-attr]
-        console.print(f"[bold]{k.replace('_', ' ').title()}:[/bold]  {v}")
-
-
-@workflows_app.command("replay")
-def workflows_replay(
-    workflow_id: str = typer.Argument(..., help="DBOS workflow ID to replay"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-    scheduler_url: str = typer.Option(
-        None,
-        "--scheduler-url",
-        envvar=_SCHEDULER_URL_ENV,
-        help="Scheduler service base URL",
-    ),
-) -> None:
-    """
-    Replay a failed or cancelled workflow from its last completed checkpoint.
-
-    Idempotent: DBOS re-enqueues on the same queue with the same workflow input.
-    The workflow resumes from the last successful step, not from scratch.
-
-    Backend: TSK-2.x  POST /api/v1/workflows/{id}/replay
-    """
-    effective_url = scheduler_url or _DEFAULT_URL
-    data = _call_service("POST", f"/api/v1/workflows/{workflow_id}/replay", effective_url)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-    else:
-        new_id = (data or {}).get("workflow_id", workflow_id)  # type: ignore[union-attr]
-        console.print(f"[green]✓ Replay enqueued.[/green]  new workflow_id: [cyan]{new_id}[/cyan]")
-
-
-@workflows_app.command("cancel")
-def workflows_cancel(
-    workflow_id: str = typer.Argument(..., help="DBOS workflow ID to cancel"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-    scheduler_url: str = typer.Option(
-        None,
-        "--scheduler-url",
-        envvar=_SCHEDULER_URL_ENV,
-        help="Scheduler service base URL",
-    ),
-) -> None:
-    """
-    Cancel an in-flight workflow (sets DBOS status to CANCELLED).
-
-    Already-completed workflows cannot be cancelled (server returns 409 Conflict).
-
-    Backend: TSK-2.x  POST /api/v1/workflows/{id}/cancel
-    """
-    effective_url = scheduler_url or _DEFAULT_URL
-    data = _call_service("POST", f"/api/v1/workflows/{workflow_id}/cancel", effective_url)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-    else:
-        console.print(f"[yellow]⏹ Workflow {workflow_id!r} cancelled.[/yellow]")
-
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# TSK-6.2: Events tail / publish
-# ═══════════════════════════════════════════════════════════════════════════════
-
-
-@events_app.command("tail")
-def events_tail(
-    topic: str | None = typer.Option(
-        None,
-        "--topic",
-        "-t",
-        help="Topic pattern to filter (e.g. 'audit.*'). Omit for all topics.",
-    ),
-    since: str | None = typer.Option(
-        None,
-        "--since",
-        help=(
-            "Events committed after this point. "
-            "In snapshot mode: duration string (e.g. 1h, 30m) — not implemented server-side yet. "
-            "In --follow mode: ISO-8601 timestamp for replay-on-reconnect."
-        ),
-    ),
-    limit: int = typer.Option(50, "--limit", "-n", help="Maximum number of recent events (snapshot mode only)"),
-    follow: bool = typer.Option(
-        False,
-        "--follow",
-        "-f",
-        help=(
-            "Live-stream events via WebSocket (TSK-11.9 Phase 2 upgrade). "
-            "Connects to WS /api/v1/events/stream and pushes events as they commit. "
-            "Press Ctrl+C to disconnect."
-        ),
-    ),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-    scheduler_url: str = typer.Option(
-        None,
-        "--scheduler-url",
-        envvar=_SCHEDULER_URL_ENV,
-        help="Scheduler service base URL",
-    ),
-) -> None:
-    """
-    Tail events from the outbox.
-
-    Default (snapshot): one-shot GET of recent sched.events_outbox rows.
-
-    Live stream (--follow / -f): connects to WS /api/v1/events/stream and
-    pushes events in real time via Postgres LISTEN/NOTIFY.  Replaces polling
-    for interactive operator use.  Press Ctrl+C to disconnect.
-
-    Backend (snapshot): TSK-3.x  GET /api/v1/events
-    Backend (live):     TSK-11.9  WS  /api/v1/events/stream
-    """
-    effective_url = scheduler_url or _DEFAULT_URL
-    if follow:
-        _events_tail_ws(topic=topic, since=since, fmt=fmt, scheduler_url=effective_url)
-        return
-
-    # ── Snapshot mode (Phase 1 default) ──────────────────────────────────────
-    params: dict = {"limit": limit}
-    if topic:
-        params["topic"] = topic
-    if since:
-        params["since"] = since
-
-    data = _call_service("GET", "/api/v1/events", effective_url, params=params)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-        return
-
-    events = data if isinstance(data, list) else (data or {}).get("events", [])  # type: ignore[union-attr]
-    if not events:
-        console.print("[yellow]No events found.[/yellow]")
-        return
-
-    table = Table(title="Events (outbox tail)", show_lines=True)
-    table.add_column("Event ID", style="cyan", no_wrap=True)
-    table.add_column("Topic", style="green")
-    table.add_column("Committed At", style="dim")
-    table.add_column("Published At", style="dim")
-    table.add_column("Trace ID", style="magenta")
-
-    for e in events:  # type: ignore[union-attr]
-        published = e.get("published_at") or "[yellow]pending[/yellow]"
-        table.add_row(
-            e.get("event_id", "?"),
-            e.get("topic", "?"),
-            e.get("committed_at", "?"),
-            published,
-            e.get("trace_id") or "—",
-        )
-    console.print(table)
-
-
-def _events_tail_ws(
-    *,
-    topic: str | None,
-    since: str | None,
-    fmt: OutputFormat,
-    scheduler_url: str,
-) -> None:
-    """
-    Live-stream events via WebSocket (TSK-11.9).
-
-    Converts the HTTP scheduler_url to a WS URL, connects to
-    ``WS /api/v1/events/stream``, and prints each arriving event
-    to stdout until the user presses Ctrl+C.
-
-    Depends on the ``websockets`` library (pulled in transitively by
-    ``fastapi[standard]`` → ``uvicorn[standard]`` → ``websockets``).
-    """
-    # Convert http(s):// → ws(s)://
-    base = scheduler_url.rstrip("/")
-    if base.startswith("https://"):
-        ws_base = "wss://" + base[len("https://") :]
-    elif base.startswith("http://"):
-        ws_base = "ws://" + base[len("http://") :]
-    else:
-        ws_base = base
-
-    # Build query string
-    qs_parts: list[str] = []
-    if topic:
-        qs_parts.append(f"topic={topic}")
-    if since:
-        qs_parts.append(f"since={since}")
-    qs = ("?" + "&".join(qs_parts)) if qs_parts else ""
-    ws_url = f"{ws_base}/api/v1/events/stream{qs}"
-
-    if fmt != OutputFormat.JSON:
-        console.print(f"[dim]Connecting to [cyan]{ws_url}[/cyan] … (Ctrl+C to stop)[/dim]")
-
-    _asyncio.run(_ws_stream_loop(ws_url=ws_url, fmt=fmt))
-
-
-async def _ws_stream_loop(*, ws_url: str, fmt: OutputFormat) -> None:
-    """
-    Async inner loop for WebSocket event streaming.
-
-    Imported lazily so the ``websockets`` library is not required when the
-    CLI is used in snapshot mode (avoids hard import at module load time).
-    """
-    try:
-        import websockets  # type: ignore[import]
-    except ImportError:
-        err_console.print(
-            "[red]websockets library is not installed.[/red]\n"
-            "[dim]It is bundled with fastapi[standard]; ensure the package is installed.[/dim]"
-        )
-        raise ImportError
-
-    try:
-        async with websockets.connect(ws_url, ping_interval=None) as ws:
-            async for raw in ws:
-                try:
-                    msg = _json.loads(raw)
-                except _json.JSONDecodeError:
-                    err_console.print(f"[yellow]Unparseable frame: {raw!r}[/yellow]")
-                    continue
-
-                # Skip control frames (type: connected / ping)
-                if "type" in msg:
-                    if msg["type"] == "connected" and fmt != OutputFormat.JSON:
-                        console.print(
-                            f"[green]✓ Stream connected[/green]  filter=[cyan]{msg.get('topic_filter') or '*'}[/cyan]"
-                        )
-                    continue
-
-                # Emit the event
-                if fmt == OutputFormat.JSON:
-                    print(_json.dumps(msg))
-                else:
-                    published = msg.get("published_at") or "[yellow]pending[/yellow]"
-                    console.print(
-                        f"[cyan]{msg.get('event_id', '?')}[/cyan]  "
-                        f"[green]{msg.get('topic', '?')}[/green]  "
-                        f"committed=[dim]{msg.get('committed_at', '?')}[/dim]  "
-                        f"published={published}  "
-                        f"trace=[magenta]{msg.get('trace_id') or '—'}[/magenta]"
-                    )
-    except KeyboardInterrupt:
-        if fmt != OutputFormat.JSON:
-            console.print("\n[dim]Disconnected.[/dim]")
-    except Exception as exc:
-        err_console.print(f"[red]WebSocket error: {exc}[/red]")
-        raise
-
-
-@events_app.command("publish")
-def events_publish(
-    topic: str = typer.Argument(..., help="Event topic (e.g. 'audit.run.completed')"),
-    payload: str = typer.Option(..., "--payload", "-p", help="JSON payload string"),
-    trace_id: str | None = typer.Option(
-        None,
-        "--trace-id",
-        "-t",
-        help="Optional distributed-trace correlation id (v2.0.15 G22). "
-        "Persisted to sched.events_outbox.trace_id; downstream subscribers "
-        "use it to stitch spans across the event boundary.",
-    ),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-    scheduler_url: str = typer.Option(
-        None,
-        "--scheduler-url",
-        envvar=_SCHEDULER_URL_ENV,
-        help="Scheduler service base URL",
-    ),
-) -> None:
-    """
-    Publish an event to the outbox.
-
-    Written to sched.events_outbox within a transaction; a Postgres trigger fires
-    pg_notify so the dispatcher picks it up immediately. Secret scanning is
-    applied server-side (FR-8.x).
-
-    Backend: TSK-N.26  POST /api/v1/events  (body carries topic, payload, trace_id)
-    """
-    effective_url = scheduler_url or _DEFAULT_URL
-    try:
-        payload_dict = _json.loads(payload)
-    except _json.JSONDecodeError as exc:
-        err_console.print(f"[red]Invalid --payload JSON: {exc}[/red]")
-        raise typer.Exit(1) from exc
-
-    body: dict = {"topic": topic, "payload": payload_dict}
-    if trace_id is not None:
-        body["trace_id"] = trace_id  # v2.0.15 G22 — opt-in trace correlation
-    data = _call_service("POST", "/api/v1/events", effective_url, json_body=body)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-    else:
-        event_id = (data or {}).get("event_id", "?")  # type: ignore[union-attr]
-        console.print(f"[green]✓ Event published to {topic!r}[/green]  event_id: [cyan]{event_id}[/cyan]")
-
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# Chains — TSK-5.x backends; CLI stubs wired per wave strategy
-# ═══════════════════════════════════════════════════════════════════════════════
-
-
-@chains_app.command("list")
-def chains_list(
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-    scheduler_url: str = typer.Option(
-        None,
-        "--scheduler-url",
-        envvar=_SCHEDULER_URL_ENV,
-        help="Scheduler service base URL",
-    ),
-) -> None:
-    """List all chain definitions."""
-    effective_url = scheduler_url or _DEFAULT_URL
-    data = _call_service("GET", "/api/v1/chains", effective_url)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-        return
-
-    chain_list = data if isinstance(data, list) else (data or {}).get("chains", [])  # type: ignore[union-attr]
-    if not chain_list:
-        console.print("[yellow]No chains configured.[/yellow]")
-        return
-
-    table = Table(title="Chain Definitions", show_lines=True)
-    table.add_column("Name", style="cyan")
-    table.add_column("Trigger", style="green")
-    table.add_column("Target Workflow", style="blue")
-    table.add_column("Queue", style="magenta")
-    table.add_column("Enabled", style="bold")
-    for c in chain_list:  # type: ignore[union-attr]
-        enabled_tag = "[green]yes[/green]" if c.get("enabled", True) else "[red]no[/red]"
-        trigger = f"{c.get('trigger_kind', '?')}:{c.get('trigger_source', '?')}"
-        table.add_row(
-            c.get("chain_name", "?"),
-            trigger,
-            c.get("target_workflow_fqn", "?"),
-            c.get("queue_name", "chain-fanout"),
-            enabled_tag,
-        )
-    console.print(table)
-
-
-@chains_app.command("show")
-def chains_show(
-    chain_name: str = typer.Argument(..., help="Chain name to inspect"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-    scheduler_url: str = typer.Option(
-        None,
-        "--scheduler-url",
-        envvar=_SCHEDULER_URL_ENV,
-        help="Scheduler service base URL",
-    ),
-) -> None:
-    """Show details for a single chain definition."""
-    effective_url = scheduler_url or _DEFAULT_URL
-    data = _call_service("GET", f"/api/v1/chains/{chain_name}", effective_url)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-    else:
-        for k, v in (data or {}).items():  # type: ignore[union-attr]
-            console.print(f"[bold]{k.replace('_', ' ').title()}:[/bold]  {v}")
-
-
-@chains_app.command("create")
-def chains_create(
-    chain_name: str = typer.Argument(..., help="Unique chain name"),
-    trigger: str = typer.Option(..., "--trigger", help="Trigger spec: event:<topic>"),
-    target: str = typer.Option(..., "--target", help="Target workflow alias or FQN"),
-    queue: str = typer.Option("chain-fanout", "--queue", "-q", help="DBOS queue name"),
-    mapping: str | None = typer.Option(None, "--mapping", help="JSONPath input mapping expression"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-    scheduler_url: str = typer.Option(
-        None,
-        "--scheduler-url",
-        envvar=_SCHEDULER_URL_ENV,
-        help="Scheduler service base URL",
-    ),
-) -> None:
-    """
-    Create a chain definition.
-
-    --trigger format: event:<topic>  (e.g. 'event:audit.run.completed')
-    --target: workflow alias or FQN
-    """
-    effective_url = scheduler_url or _DEFAULT_URL
-    if ":" not in trigger:
-        err_console.print(
-            f"[red]Invalid --trigger {trigger!r}: expected '<kind>:<source>', e.g. "
-            f"'event:audit.run.completed' or 'complete:vds_audit_orchestrator.workflows.audit_drift_scan.audit_drift_scan'[/red]"
-        )
-        raise typer.Exit(1)
-    kind_token, _, trigger_source = trigger.partition(":")
-    _kind_alias = {"event": "on_event", "complete": "on_complete"}
-    trigger_kind = _kind_alias.get(kind_token, kind_token)
-    if trigger_kind not in ("on_event", "on_complete"):
-        err_console.print(
-            f"[red]Invalid trigger kind {kind_token!r}: must be 'event' / 'on_event' or 'complete' / 'on_complete'[/red]"
-        )
-        raise typer.Exit(1)
-
-    body: dict = {
-        "chain_name": chain_name,
-        "trigger_kind": trigger_kind,
-        "trigger_source": trigger_source,
-        "target_workflow_fqn": target,
-        "queue_name": queue,
-    }
-    if mapping:
-        body["input_mapping_jsonpath"] = mapping
-
-    data = _call_service("POST", "/api/v1/chains", effective_url, json_body=body)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-    else:
-        console.print(f"[green]✓ Chain {chain_name!r} created.[/green]")
-
-
-@chains_app.command("delete")
-def chains_delete(
-    chain_name: str = typer.Argument(..., help="Chain name to delete"),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
-    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format", help=_FORMAT_HELP),
-    scheduler_url: str = typer.Option(
-        None,
-        "--scheduler-url",
-        envvar=_SCHEDULER_URL_ENV,
-        help="Scheduler service base URL",
-    ),
-) -> None:
-    """Delete a chain definition."""
-    effective_url = scheduler_url or _DEFAULT_URL
-    if not yes:
-        confirmed = typer.confirm(f"Delete chain {chain_name!r}?", default=False)
-        if not confirmed:
-            console.print("[yellow]Aborted.[/yellow]")
-            raise typer.Exit(0)
-
-    data = _call_service("DELETE", f"/api/v1/chains/{chain_name}", effective_url)
-    if fmt == OutputFormat.JSON:
-        _print_json(data)
-    else:
-        console.print(f"[red]✗ Chain {chain_name!r} deleted.[/red]")
-
-
-# ── Entry point ───────────────────────────────────────────────────────────────
-
-if __name__ == "__main__":
-    app()