@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/ecosystem/__init__.py

@@ -0,0 +1,39 @@
+"""vds-cli ecosystem subcommand group.
+
+Implements TSK-P3-0.1 from .gpt-5.4/specs/ecosystem-daily-report/tasks.md
+(Phase 3, Wave 0).
+
+This package provides the operator-facing CLI dashboard for the Ecosystem
+Daily Report (`scheduler_orchestrator`). Subcommands query the
+`sched.ecosystem_report_runs` Postgres table directly to render historical
+runs, metric trends with sparklines, and anomaly aggregations.
+
+Layout:
+    ecosystem/
+        __init__.py     -- top-level Typer app + `report` subgroup binding
+        report.py       -- history / trends / anomalies command implementations
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .report import report_app
+
+ecosystem_app = typer.Typer(
+    help=(
+        "Ecosystem Daily Report dashboard — query historical runs, metric "
+        "trends with sparklines, and anomaly aggregations from "
+        "sched.ecosystem_report_runs. Spec: "
+        ".gpt-5.4/specs/ecosystem-daily-report/."
+    ),
+)
+
+ecosystem_app.add_typer(
+    report_app,
+    name="report",
+    help="Daily ecosystem report dashboard subcommands.",
+)
+
+
+__all__ = ["ecosystem_app"]

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/ecosystem/report.py

@@ -0,0 +1,439 @@
+"""Ecosystem Daily Report dashboard commands.
+
+Implements TSK-P3-3.1 / TSK-P3-3.2 / TSK-P3-3.3 from
+``.gpt-5.4/specs/ecosystem-daily-report/tasks.md``.
+
+The three subcommands all read from the Postgres table
+``sched.ecosystem_report_runs``:
+
+* ``vds-cli ecosystem report history --days N`` — table of last N runs.
+* ``vds-cli ecosystem report trends --metric NAME`` — sparkline + stats.
+* ``vds-cli ecosystem report anomalies --days N`` — anomaly frequency report.
+
+Design notes
+------------
+* SQLAlchemy and ``DATABASE_URL`` resolution are imported lazily so that
+  ``vds-cli ecosystem --help`` still works in environments that have not
+  installed the scheduler runtime.
+* All three commands route empty results through ``_render_empty_state``
+  so the banner shape stays consistent (Wave 3.3).
+* Sparkline characters match the spec verbatim: ``▁▂▃▄▅▆▇█``. With fewer
+  than ``SPARKLINE_MIN_POINTS`` (3) values, ``render_sparkline_with_hint``
+  appends an explicit "trend insufficient" hint so a single-bar sparkline
+  is not misread as a trend (Wave 3.2).
+* ``--days`` must be a positive integer; ``typer.BadParameter`` is raised
+  otherwise.
+* The ``history`` table folds long columns by default (``overflow="fold"``)
+  so an 80-col terminal does not silently truncate the report path
+  (Wave 3.1). Pass ``--full`` to force untruncated rendering.
+* NULL cells in ``history`` render as ``[dim]—[/dim]`` so operators can
+  see "data not yet populated" at a glance (Wave 3.4).
+"""
+
+from __future__ import annotations
+
+import os
+from collections import Counter
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+report_app = typer.Typer(
+    help=(
+        "Query the daily ecosystem report archive in "
+        "sched.ecosystem_report_runs."
+    ),
+)
+
+
+# ── Shared rendering helpers ─────────────────────────────────────────────────
+
+# Sentinel rendered for NULL columns. Wrapped in Rich `[dim]` so operators
+# can visually distinguish "data not yet populated" (Phase-3-pending columns)
+# from a literal value at a glance (Wave 3.4).
+NULL_CELL: str = "[dim]—[/dim]"
+
+# Shared empty-state banner used by all three subcommands so the output
+# shape is consistent (Wave 3.3).
+EMPTY_STATE_BANNER: str = "[yellow]No data available[/yellow]"
+
+
+def _render_empty_state(suffix: str = "") -> None:
+    """Render the canonical empty-state banner.
+
+    All three commands route through this helper so the operator sees the
+    same shape regardless of which subcommand they run. ``suffix`` is an
+    optional trailing string (e.g. ``" for metric 'health_score'"``) that
+    keeps the metric-specific hint while preserving banner shape.
+    """
+    console.print(f"{EMPTY_STATE_BANNER}{suffix}")
+
+
+def _fmt_nullable(value: Any) -> str:
+    """Format a possibly-NULL cell value.
+
+    Returns the dim-grey sentinel for ``None``; otherwise stringifies the
+    value. Used for Phase-3-pending columns in history rows so missing
+    data reads as "not yet populated", not as a literal em-dash (Wave 3.4).
+    """
+    if value is None:
+        return NULL_CELL
+    return str(value)
+
+
+# ── Sparkline rendering (spec: ▁▂▃▄▅▆▇█) ─────────────────────────────────────
+
+SPARKLINE_BARS: tuple[str, ...] = ("▁", "▂", "▃", "▄", "▅", "▆", "▇", "█")
+
+# Numeric metrics whitelisted for the `trends` command. These are top-level
+# columns on `sched.ecosystem_report_runs` (Phase 1 + Phase 2). When a new
+# numeric column is added in a later phase, append it here.
+TREND_METRICS: tuple[str, ...] = (
+    "health_score",
+    "error_24h",
+    "success_24h",
+    "pending_depth",
+    "enqueued_depth",
+    "generation_duration_ms",
+)
+
+
+def render_sparkline(values: list[float]) -> str:
+    """Render a Unicode sparkline for a numeric series.
+
+    Returns an empty string for an empty series. Constant series collapse
+    to the lowest bar character — this matches the spec design.md
+    pseudocode (the formatter never crashes on a flat series).
+    """
+    if not values:
+        return ""
+    lo = min(values)
+    hi = max(values)
+    if hi == lo:
+        return SPARKLINE_BARS[0] * len(values)
+    span = hi - lo
+    n = len(SPARKLINE_BARS) - 1
+    return "".join(SPARKLINE_BARS[int((v - lo) / span * n)] for v in values)
+
+
+# Minimum number of points required for a sparkline to convey a meaningful
+# trend. With N=1 the sparkline is just ``▁`` (min=avg=max=latest); with
+# N=2 the trend is ambiguous. Below this threshold the renderer appends
+# an explicit hint so operators don't misread the bar (Wave 3.2).
+SPARKLINE_MIN_POINTS: int = 3
+
+
+def render_sparkline_with_hint(values: list[float]) -> str:
+    """Render a sparkline; append a "trend insufficient" hint when N < 3.
+
+    Returns the bare sparkline when there are enough points; otherwise
+    returns ``"<spark> (trend insufficient: N=<count>, need ≥3)"`` so the
+    operator immediately knows the bar is not a trend signal.
+    """
+    spark = render_sparkline(values)
+    count = len(values)
+    if count < SPARKLINE_MIN_POINTS:
+        return (
+            f"{spark} (trend insufficient: N={count}, "
+            f"need ≥{SPARKLINE_MIN_POINTS})"
+        )
+    return spark
+
+
+# ── Database access helpers (lazy SQLAlchemy import) ─────────────────────────
+
+
+def _get_database_url() -> str:
+    """Resolve the Postgres DSN for the scheduler database.
+
+    Mirrors `scheduler_orchestrator.config.EcosystemSchedulerConfig`: the
+    canonical env var is ``DATABASE_URL``. We do not import the scheduler
+    config module here to keep the CLI independent of the orchestrator
+    runtime (which may not be installed for plain operators).
+    """
+    url = os.environ.get("DATABASE_URL")
+    if not url:
+        raise typer.BadParameter(
+            "DATABASE_URL is not set. Configure the scheduler Postgres DSN "
+            "in ~/.vds/.env (key: DATABASE_URL).",
+            param_hint="env:DATABASE_URL",
+        )
+    return url
+
+
+def _make_session() -> Any:
+    """Lazily build a SQLAlchemy session bound to the scheduler DSN.
+
+    Returns a context-manageable Session. Tests patch this function
+    directly to avoid touching real Postgres.
+    """
+    from sqlalchemy import create_engine
+    from sqlalchemy.orm import sessionmaker
+
+    engine = create_engine(_get_database_url())
+    factory = sessionmaker(bind=engine, expire_on_commit=False)
+    return factory()
+
+
+def _validate_days(days: int) -> int:
+    """Coerce/validate the --days argument."""
+    if days <= 0:
+        raise typer.BadParameter(
+            f"--days must be a positive integer, got {days}.",
+            param_hint="'--days'",
+        )
+    return days
+
+
+# ── Commands ─────────────────────────────────────────────────────────────────
+
+
+@report_app.command("history")
+def history(
+    days: Annotated[
+        int,
+        typer.Option(
+            "--days",
+            "-d",
+            help="Number of recent runs to display (most recent first).",
+        ),
+    ] = 7,
+    full: Annotated[
+        bool,
+        typer.Option(
+            "--full/--no-full",
+            help=(
+                "Force full-width rendering instead of folding long columns. "
+                "Default folds long timestamps and report paths so the table "
+                "fits in an 80-column terminal."
+            ),
+        ),
+    ] = False,
+) -> None:
+    """Show the last N ecosystem report runs as a table.
+
+    Columns: report_date, generated_at, health_score, error_24h,
+    success_24h, anomaly_count, report_path. Long columns
+    (``generated_at``, ``report_path``) fold by default to fit narrow
+    terminals; pass ``--full`` to disable folding.
+    """
+    n = _validate_days(days)
+    from sqlalchemy import text
+
+    sql = text(
+        """
+        SELECT report_date,
+               generated_at,
+               health_score,
+               error_24h,
+               success_24h,
+               anomalies,
+               report_path
+        FROM sched.ecosystem_report_runs
+        ORDER BY report_date DESC
+        LIMIT :limit
+        """
+    )
+
+    with _make_session() as session:
+        rows = list(session.execute(sql, {"limit": n}))
+
+    if not rows:
+        _render_empty_state()
+        return
+
+    # Wave 3.1 — long columns fold by default so an 80-col terminal does
+    # not silently truncate to "report_da…". Operators who want the full
+    # untruncated table pass ``--full``.
+    overflow = "ignore" if full else "fold"
+    table = Table(title=f"Ecosystem Report — last {len(rows)} run(s)")
+    table.add_column("report_date", style="cyan", overflow=overflow)
+    table.add_column("generated_at", style="white", overflow=overflow)
+    table.add_column("health", justify="right", overflow=overflow)
+    table.add_column("err_24h", justify="right", style="red", overflow=overflow)
+    table.add_column(
+        "ok_24h", justify="right", style="green", overflow=overflow
+    )
+    table.add_column("anomalies", justify="right", overflow=overflow)
+    table.add_column("report_path", style="dim", overflow=overflow)
+
+    for row in rows:
+        anomaly_payload = row.anomalies or {}
+        if isinstance(anomaly_payload, dict):
+            anomaly_count = len(anomaly_payload.get("items", []) or [])
+        elif isinstance(anomaly_payload, list):
+            anomaly_count = len(anomaly_payload)
+        else:
+            anomaly_count = 0
+        table.add_row(
+            _fmt_nullable(row.report_date),
+            _fmt_nullable(row.generated_at),
+            _fmt_nullable(row.health_score),
+            _fmt_nullable(row.error_24h),
+            _fmt_nullable(row.success_24h),
+            str(anomaly_count),
+            _fmt_nullable(row.report_path),
+        )
+    console.print(table)
+
+
+@report_app.command("trends")
+def trends(
+    metric: Annotated[
+        str,
+        typer.Option(
+            "--metric",
+            "-m",
+            help=(
+                "Numeric metric to trend. Allowed: "
+                + ", ".join(TREND_METRICS)
+                + "."
+            ),
+        ),
+    ] = "health_score",
+    days: Annotated[
+        int,
+        typer.Option(
+            "--days",
+            "-d",
+            help="History window (most-recent-first ordering).",
+        ),
+    ] = 7,
+) -> None:
+    """Show a sparkline + summary statistics for a metric over the window."""
+    if metric not in TREND_METRICS:
+        raise typer.BadParameter(
+            f"Unknown metric '{metric}'. Allowed metrics: "
+            f"{', '.join(TREND_METRICS)}.",
+            param_hint="'--metric'",
+        )
+    n = _validate_days(days)
+
+    from sqlalchemy import text
+
+    # Column name is whitelisted above, so safe to interpolate.
+    sql = text(
+        f"""
+        SELECT report_date, {metric} AS value
+        FROM sched.ecosystem_report_runs
+        WHERE {metric} IS NOT NULL
+        ORDER BY report_date DESC
+        LIMIT :limit
+        """
+    )
+    with _make_session() as session:
+        rows = list(session.execute(sql, {"limit": n}))
+
+    if not rows:
+        _render_empty_state(suffix=f" for metric '{metric}'")
+        return
+
+    # Reverse so the sparkline reads oldest → newest, left-to-right.
+    ordered = list(reversed(rows))
+    values = [float(r.value) for r in ordered]
+    # Wave 3.2 — append a "trend insufficient" hint when N < 3 so a
+    # single-bar sparkline isn't mistaken for a trend signal.
+    spark = render_sparkline_with_hint(values)
+
+    avg = sum(values) / len(values)
+    table = Table(title=f"Trend — {metric} (last {len(values)} run(s))")
+    table.add_column("metric", style="cyan")
+    table.add_column("sparkline", style="magenta")
+    table.add_column("min", justify="right")
+    table.add_column("avg", justify="right")
+    table.add_column("max", justify="right")
+    table.add_column("latest", justify="right")
+    table.add_row(
+        metric,
+        spark,
+        f"{min(values):g}",
+        f"{avg:.2f}",
+        f"{max(values):g}",
+        f"{values[-1]:g}",
+    )
+    console.print(table)
+
+
+@report_app.command("anomalies")
+def anomalies(
+    days: Annotated[
+        int,
+        typer.Option(
+            "--days",
+            "-d",
+            help="Lookback window in days (most-recent-first).",
+        ),
+    ] = 30,
+) -> None:
+    """Aggregate anomaly frequency over the last N runs.
+
+    Reads the JSONB ``anomalies`` column. Each row's payload is expected
+    to follow either the ``{"items": [str, ...]}`` shape (Phase 1) or a
+    bare ``[str, ...]`` list. Unknown shapes are skipped.
+    """
+    n = _validate_days(days)
+    from sqlalchemy import text
+
+    sql = text(
+        """
+        SELECT report_date, anomalies
+        FROM sched.ecosystem_report_runs
+        ORDER BY report_date DESC
+        LIMIT :limit
+        """
+    )
+    with _make_session() as session:
+        rows = list(session.execute(sql, {"limit": n}))
+
+    if not rows:
+        _render_empty_state()
+        return
+
+    counter: Counter[str] = Counter()
+    runs_with_any = 0
+    for row in rows:
+        payload = row.anomalies or {}
+        if isinstance(payload, dict):
+            items = payload.get("items") or []
+        elif isinstance(payload, list):
+            items = payload
+        else:
+            items = []
+        if items:
+            runs_with_any += 1
+        for item in items:
+            counter[str(item)] += 1
+
+    if not counter:
+        console.print(
+            f"[green]No anomalies in last {len(rows)} run(s)[/green]"
+        )
+        return
+
+    table = Table(
+        title=(
+            f"Anomaly frequency — last {len(rows)} run(s) "
+            f"({runs_with_any} run(s) flagged)"
+        )
+    )
+    table.add_column("count", justify="right", style="red")
+    table.add_column("anomaly", style="white")
+    for label, count in counter.most_common():
+        table.add_row(str(count), label)
+    console.print(table)
+
+
+__all__ = [
+    "EMPTY_STATE_BANNER",
+    "NULL_CELL",
+    "SPARKLINE_BARS",
+    "SPARKLINE_MIN_POINTS",
+    "TREND_METRICS",
+    "render_sparkline",
+    "render_sparkline_with_hint",
+    "report_app",
+]

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/ecosystem_docs.py

@@ -0,0 +1,164 @@
+"""Ecosystem-wide documentation index generation."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class EcosystemDocEntry:
+    repo: str
+    path: Path
+    title: str
+    quadrant: str
+    line_count: int
+    language: str  # "en" | "vi"
+
+
+def discover_repos(base_path: Path) -> list[Path]:
+    """Discover all repos with doc surfaces under base_path."""
+    known = ["vds-scripts", "vds-skills", "vds-ai-memory"]
+    repos = []
+    for name in known:
+        candidate = base_path / name
+        if candidate.is_dir() and (candidate / "AGENTS.md").exists():
+            repos.append(candidate)
+    return repos
+
+
+def scan_repo_docs(repo_path: Path) -> list[EcosystemDocEntry]:
+    """Scan a single repo for all docs."""
+    entries: list[EcosystemDocEntry] = []
+    diataxis_html_re = re.compile(r"\u003c!--\s*di[áà]taxis:\s*([\w-]+)\s*--\u003e", re.IGNORECASE)
+    diataxis_yaml_re = re.compile(r"^di[áà]taxis:\s*([\w-]+)\s*$", re.IGNORECASE)
+
+    for lang in ["en", "vi"]:
+        docs_dir = repo_path / "docs" / (lang if lang == "vi" else "agents")
+        if lang == "en":
+            docs_dir = repo_path / "docs" / "agents"
+        if not docs_dir.exists():
+            continue
+
+        for md_path in sorted(docs_dir.rglob("*.md")):
+            text = md_path.read_text(encoding="utf-8")
+            lines = text.splitlines()
+            lines[0] if lines else ""
+
+            quadrant = "uncategorized"
+            for line in lines[:10]:
+                m = diataxis_html_re.search(line)
+                if m:
+                    quadrant = m.group(1).lower()
+                    break
+                m = diataxis_yaml_re.search(line)
+                if m:
+                    quadrant = m.group(1).lower()
+                    break
+
+            # Handle YAML-frontmatter titles (--- block before H1)
+            title = md_path.stem.replace("-", " ").title()
+            for idx, line in enumerate(lines):
+                if line.strip() == "---" and idx > 0:
+                    # End of YAML frontmatter; next non-empty should be H1
+                    for next_line in lines[idx + 1 :]:
+                        title_match = re.match(r"^#\s+(.+)$", next_line)
+                        if title_match:
+                            title = title_match.group(1)
+                            break
+                    break
+                if idx == 0 and line.strip() != "---":
+                    # No YAML frontmatter; title may be first line
+                    title_match = re.match(r"^#\s+(.+)$", line)
+                    if title_match:
+                        title = title_match.group(1)
+                    break
+
+            entries.append(
+                EcosystemDocEntry(
+                    repo=repo_path.name,
+                    path=md_path.relative_to(repo_path),
+                    title=title,
+                    quadrant=quadrant,
+                    line_count=len(lines),
+                    language=lang,
+                )
+            )
+
+    return entries
+
+
+def generate_ecosystem_index(base_path: Path, output: Path) -> dict[str, Any]:
+    """Generate ECOSYSTEM-DOCS.md from discovered repos."""
+    repos = discover_repos(base_path)
+    all_entries: list[EcosystemDocEntry] = []
+    for repo in repos:
+        all_entries.extend(scan_repo_docs(repo))
+
+    lines = [
+        "# WHO Ecosystem Documentation Index",
+        "",
+        "> Auto-generated from repo doc surfaces. Do not edit manually.",
+        f"> Generated: {__import__('datetime').datetime.now(__import__('datetime').UTC).isoformat()}",
+        "",
+        "## By Repository",
+        "",
+    ]
+
+    for repo in repos:
+        repo_entries = [e for e in all_entries if e.repo == repo.name]
+        lines.append(f"### {repo.name} ({len(repo_entries)} docs)")
+        lines.append("")
+        lines.append("| Doc | Quadrant | Lines | Language |")
+        lines.append("|-----|----------|-------|----------|")
+        for e in sorted(repo_entries, key=lambda x: (x.language, x.quadrant, x.title)):
+            rel = str(e.path)
+            lines.append(f"| [{e.title}](./{e.repo}/{rel}) | {e.quadrant} | {e.line_count} | {e.language} |")
+        lines.append("")
+
+    lines.extend(
+        [
+            "## By Diátaxis Quadrant",
+            "",
+        ]
+    )
+
+    quadrants = ["tutorial", "how-to", "reference", "explanation"]
+    for q in quadrants:
+        q_entries = [e for e in all_entries if e.quadrant == q]
+        lines.append(f"### {q.title()}")
+        lines.append("")
+        for e in sorted(q_entries, key=lambda x: (x.repo, x.title)):
+            lines.append(f"- [{e.title}](./{e.repo}/{e.path}) ({e.repo}, {e.language})")
+        lines.append("")
+
+    lines.extend(
+        [
+            "## By Language",
+            "",
+            "### English",
+            "",
+        ]
+    )
+    for e in sorted([x for x in all_entries if x.language == "en"], key=lambda x: (x.repo, x.title)):
+        lines.append(f"- [{e.title}](./{e.repo}/{e.path}) ({e.repo})")
+
+    lines.extend(
+        [
+            "",
+            "### Vietnamese (Tiếng Việt)",
+            "",
+        ]
+    )
+    for e in sorted([x for x in all_entries if x.language == "vi"], key=lambda x: (x.repo, x.title)):
+        lines.append(f"- [{e.title}](./{e.repo}/{e.path}) ({e.repo})")
+
+    output.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    return {
+        "repos": len(repos),
+        "docs": len(all_entries),
+        "output": str(output),
+    }