@suiflex/suitest-mcp 0.1.0

package/python/suitest_lifecycle/readiness.py

@@ -0,0 +1,83 @@
+"""Readiness detection — never run tests against a server that isn't up.
+
+Strategies, tried in order until one succeeds within the timeout:
+  1. HTTP probe of the ready URL (any < 500 response counts as "alive").
+  2. TCP port-open check (fallback when there's no health route).
+  3. Ready-log pattern match (when the process emits a known "listening" line).
+
+Returns a :class:`Readiness` verdict with the strategy that succeeded, or
+``ready=False`` with the elapsed time so the caller can mark the run failed and
+attach the startup log.
+"""
+
+from __future__ import annotations
+
+import socket
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+@dataclass(frozen=True)
+class Readiness:
+    ready: bool
+    strategy: str
+    detail: str
+    waited_ms: int
+
+
+def _http_ok(url: str, timeout: float) -> bool:
+    req = urllib.request.Request(url, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return int(resp.status) < 500
+    except urllib.error.HTTPError as exc:
+        return int(exc.code) < 500  # 401/404 still means the server is alive
+    except (TimeoutError, urllib.error.URLError, ConnectionError, OSError):
+        return False
+
+
+def _port_open(host: str, port: int, timeout: float) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+def wait_until_ready(
+    ready_url: str,
+    host: str,
+    port: int,
+    timeout_sec: int,
+    *,
+    log_reader: Callable[[], str] | None = None,
+    ready_log_pattern: str = "",
+    poll_interval: float = 0.5,
+    monotonic: Callable[[], float] = time.monotonic,
+    sleep: Callable[[float], None] = time.sleep,
+) -> Readiness:
+    """Block until the target is ready or the timeout elapses."""
+    start = monotonic()
+    deadline = start + timeout_sec
+    while monotonic() < deadline:
+        if _http_ok(ready_url, timeout=min(5.0, poll_interval * 4)):
+            return Readiness(True, "http", f"GET {ready_url} alive", _ms(start, monotonic))
+        if _port_open(host, port, timeout=min(2.0, poll_interval * 2)):
+            return Readiness(True, "port", f"tcp {host}:{port} open", _ms(start, monotonic))
+        if ready_log_pattern and log_reader is not None and ready_log_pattern in log_reader():
+            return Readiness(True, "log", f"matched '{ready_log_pattern}'", _ms(start, monotonic))
+        sleep(poll_interval)
+    return Readiness(False, "timeout", f"not ready after {timeout_sec}s", _ms(start, monotonic))
+
+
+def _ms(start: float, monotonic: Callable[[], float]) -> int:
+    return int((monotonic() - start) * 1000)
+
+
+__all__ = ["Readiness", "wait_until_ready"]

package/python/suitest_lifecycle/report.py

@@ -0,0 +1,179 @@
+"""Human + machine readable reports.
+
+Writes:
+  * ``tmp/raw_report.md``     — TestSprite-style per-test report (metadata,
+    requirement validation, coverage, gaps/risks).
+  * ``reports/summary.json``  — machine summary for CI.
+  * ``reports/summary.md``    — cross-mode rollup developers/QA/PO can skim.
+  * ``reports/summary.html``  — standalone styled page (no external assets).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from suitest_lifecycle.models import RunSummary, TestOutcome, TestResult
+from suitest_lifecycle.serialize import summary_to_json
+
+if TYPE_CHECKING:
+    from suitest_lifecycle.paths import Paths
+
+_BADGE = {
+    TestOutcome.PASSED: "✅ Passed",
+    TestOutcome.FAILED: "❌ Failed",
+    TestOutcome.SKIPPED: "⏭️ Skipped",
+    TestOutcome.ERROR: "🔥 Error",
+}
+
+
+def _gaps(summary: RunSummary) -> list[str]:
+    gaps: list[str] = []
+    if not summary.ready:
+        gaps.append(
+            f"Target never became ready ({summary.ready_detail}); tests could not run reliably."
+        )
+    failed = [r for r in summary.results if r.status in (TestOutcome.FAILED, TestOutcome.ERROR)]
+    for r in failed:
+        first = (r.error or "").splitlines()[-1] if r.error else "no error captured"
+        gaps.append(f"{r.test_id} {r.title}: {first}")
+    if not gaps:
+        gaps.append("No gaps detected — all generated requirements passed.")
+    return gaps
+
+
+def write_raw_report(summary: RunSummary, paths: Paths, date: str) -> None:
+    lines: list[str] = []
+    lines.append("# Suitest Testing Report")
+    lines.append("")
+    lines.append("## 1️⃣ Document Metadata")
+    lines.append(f"- **Project:** {summary.project}")
+    lines.append(f"- **Mode:** {summary.mode.value}")
+    lines.append(f"- **Base URL:** {summary.base_url}")
+    lines.append(f"- **Date:** {date}")
+    lines.append("- **Prepared by:** Suitest")
+    lines.append(
+        f"- **Summary:** {summary.total} tests — {summary.passed} passed, "
+        f"{summary.failed} failed, {summary.skipped} skipped, {summary.errored} error "
+        f"({summary.duration_ms} ms)"
+    )
+    lines.append(
+        f"- **Readiness:** {'ready' if summary.ready else 'NOT READY'} ({summary.ready_detail})"
+    )
+    lines.append("")
+    lines.append("## 2️⃣ Requirement Validation Summary")
+    for r in summary.results:
+        lines.append("")
+        lines.append(f"### {r.test_id} {r.title}")
+        lines.append(f"- **Status:** {_BADGE[r.status]}")
+        lines.append(f"- **Description:** {r.description}")
+        lines.append(f"- **Duration:** {r.duration_ms} ms")
+        if r.automation_file:
+            lines.append(f"- **Automation:** `{r.automation_file}`")
+        if r.error:
+            lines.append("- **Error:**")
+            lines.append("```")
+            lines.extend(r.error.splitlines())
+            lines.append("```")
+    lines.append("")
+    lines.append("## 3️⃣ Coverage & Matching Metrics")
+    pct = (summary.passed / summary.total * 100) if summary.total else 0.0
+    lines.append(f"- Pass rate: **{pct:.0f}%** ({summary.passed}/{summary.total})")
+    by_cat = _coverage_by_outcome(summary.results)
+    lines.append("")
+    lines.append("| Outcome | Count |")
+    lines.append("|---------|-------|")
+    for name, count in by_cat:
+        lines.append(f"| {name} | {count} |")
+    lines.append("")
+    lines.append("## 4️⃣ Key Gaps / Risks")
+    for g in _gaps(summary):
+        lines.append(f"- {g}")
+    lines.append("")
+    paths.raw_report_md.write_text("\n".join(lines), encoding="utf-8")
+
+
+def _coverage_by_outcome(results: list[TestResult]) -> list[tuple[str, int]]:
+    counts: dict[str, int] = {}
+    for r in results:
+        counts[r.status.value] = counts.get(r.status.value, 0) + 1
+    return sorted(counts.items())
+
+
+def write_summary_json(summary: RunSummary, paths: Paths) -> None:
+    paths.reports_dir.mkdir(parents=True, exist_ok=True)
+    payload = summary_to_json(summary)
+    (paths.reports_dir / "summary.json").write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def write_summary_md(summary: RunSummary, paths: Paths) -> None:
+    paths.reports_dir.mkdir(parents=True, exist_ok=True)
+    pct = (summary.passed / summary.total * 100) if summary.total else 0.0
+    lines = [
+        f"# Suitest Summary — {summary.project}",
+        "",
+        f"- Mode: **{summary.mode.value}** · Base URL: `{summary.base_url}`",
+        f"- Ready: **{'yes' if summary.ready else 'NO'}** ({summary.ready_detail})",
+        f"- Result: **{summary.passed}/{summary.total} passed ({pct:.0f}%)** in {summary.duration_ms} ms",
+        f"- Failed: {summary.failed} · Skipped: {summary.skipped} · Error: {summary.errored}",
+        "",
+        "| Test | Status | ms |",
+        "|------|--------|----|",
+    ]
+    for r in summary.results:
+        lines.append(f"| {r.test_id} {r.title} | {_BADGE[r.status]} | {r.duration_ms} |")
+    (paths.reports_dir / "summary.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def write_summary_html(summary: RunSummary, paths: Paths) -> None:
+    paths.reports_dir.mkdir(parents=True, exist_ok=True)
+    pct = (summary.passed / summary.total * 100) if summary.total else 0.0
+    rows = "\n".join(
+        f"<tr class='{r.status.value.lower()}'><td>{r.test_id}</td><td>{_esc(r.title)}</td>"
+        f"<td>{r.status.value}</td><td>{r.duration_ms}</td><td><pre>{_esc(r.error)}</pre></td></tr>"
+        for r in summary.results
+    )
+    html = f"""<!doctype html><html><head><meta charset="utf-8">
+<title>Suitest — {_esc(summary.project)}</title>
+<style>
+ body{{font-family:ui-sans-serif,system-ui,sans-serif;background:#0a0a0a;color:#fafafa;margin:0;padding:2rem}}
+ h1{{font-size:1.4rem}} .meta{{color:#a3a3a3;margin-bottom:1rem}}
+ table{{border-collapse:collapse;width:100%;font-size:.85rem}}
+ th,td{{border:1px solid #262626;padding:.4rem .6rem;text-align:left;vertical-align:top}}
+ th{{background:#161616}} pre{{margin:0;white-space:pre-wrap;color:#f87171;font-size:.75rem}}
+ tr.passed td:nth-child(3){{color:#4ade80}} tr.failed td:nth-child(3),tr.error td:nth-child(3){{color:#f87171}}
+ .pill{{display:inline-block;padding:.2rem .6rem;border-radius:999px;background:#161616;margin-right:.4rem}}
+</style></head><body>
+<h1>Suitest Report — {_esc(summary.project)} ({summary.mode.value})</h1>
+<div class="meta">
+ <span class="pill">Base: {_esc(summary.base_url)}</span>
+ <span class="pill">Ready: {"yes" if summary.ready else "NO"}</span>
+ <span class="pill">Pass: {summary.passed}/{summary.total} ({pct:.0f}%)</span>
+ <span class="pill">{summary.duration_ms} ms</span>
+</div>
+<table><thead><tr><th>ID</th><th>Title</th><th>Status</th><th>ms</th><th>Error</th></tr></thead>
+<tbody>{rows}</tbody></table>
+</body></html>"""
+    (paths.reports_dir / "summary.html").write_text(html, encoding="utf-8")
+
+
+def _esc(text: str) -> str:
+    return (
+        text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;")
+    )
+
+
+def write_all_reports(summary: RunSummary, paths: Paths, date: str) -> None:
+    write_raw_report(summary, paths, date)
+    write_summary_json(summary, paths)
+    write_summary_md(summary, paths)
+    write_summary_html(summary, paths)
+
+
+__all__ = [
+    "write_all_reports",
+    "write_raw_report",
+    "write_summary_html",
+    "write_summary_json",
+    "write_summary_md",
+]

package/python/suitest_lifecycle/runner.py

@@ -0,0 +1,138 @@
+"""Execute exported test files and collect structured results.
+
+Each ``TCxxx.py`` is runnable standalone (its ``__main__`` calls the test fn), so
+we execute it with the current interpreter, capture stdout/stderr, and map the
+exit code to a :class:`TestResult`. A non-zero exit (e.g. ``AssertionError``)
+becomes ``FAILED`` with the captured traceback as the error message.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import time
+from typing import TYPE_CHECKING
+
+from suitest_lifecycle.models import PlanCase, StepResult, TestOutcome, TestResult
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _collect_steps(
+    case: PlanCase, test_dir: Path, outcome: TestOutcome
+) -> tuple[list[StepResult], str, str]:
+    """Read the test's ``<TC>.result.json`` sidecar (frontend) or derive steps
+    from the plan (backend). Returns (steps, video_path, screenshot_path)."""
+    sidecar = test_dir / f"{case.id}.result.json"
+    if sidecar.is_file():
+        try:
+            data = json.loads(sidecar.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            data = {}
+        steps = [
+            StepResult(
+                index=int(s.get("index", i + 1)),
+                type=str(s.get("type", "action")),
+                description=str(s.get("description", "")),
+                status=_as_outcome(str(s.get("status", "PASSED"))),
+                screenshot_path=str(s.get("screenshot") or ""),
+            )
+            for i, s in enumerate(data.get("steps", []) or [])
+            if isinstance(s, dict)
+        ]
+        return steps, str(data.get("video") or ""), str(data.get("screenshot") or "")
+    # Backend (no sidecar): derive from the plan steps, marking the last failed
+    # when the test failed so the Steps panel still shows where it broke.
+    steps = []
+    n = len(case.steps)
+    for i, ps in enumerate(case.steps):
+        st = TestOutcome.PASSED
+        if outcome in (TestOutcome.FAILED, TestOutcome.ERROR) and i == n - 1:
+            st = outcome
+        steps.append(StepResult(index=i + 1, type=ps.type, description=ps.description, status=st))
+    return steps, "", ""
+
+
+def _as_outcome(value: str) -> TestOutcome:
+    try:
+        return TestOutcome(value.upper())
+    except ValueError:
+        return TestOutcome.PASSED
+
+
+def _run_one(file_path: Path, python: str, timeout_sec: int) -> tuple[TestOutcome, int, str]:
+    start = time.monotonic()
+    try:
+        proc = subprocess.run(
+            [python, str(file_path)],
+            capture_output=True,
+            text=True,
+            timeout=timeout_sec,
+            cwd=str(file_path.parent),
+        )
+    except subprocess.TimeoutExpired:
+        return (
+            TestOutcome.ERROR,
+            int((time.monotonic() - start) * 1000),
+            f"timeout after {timeout_sec}s",
+        )
+    duration_ms = int((time.monotonic() - start) * 1000)
+    if proc.returncode == 0:
+        return TestOutcome.PASSED, duration_ms, ""
+    err = (proc.stderr or "").strip() or (proc.stdout or "").strip() or f"exit {proc.returncode}"
+    # Keep the last ~30 lines — enough to see the assertion without flooding the report.
+    err_tail = "\n".join(err.splitlines()[-30:])
+    return TestOutcome.FAILED, duration_ms, err_tail
+
+
+def run_tests(
+    cases: list[PlanCase],
+    test_dir: Path,
+    *,
+    selected_ids: list[str] | None = None,
+    python: str | None = None,
+    timeout_sec: int = 120,
+) -> list[TestResult]:
+    interpreter = python or sys.executable
+    wanted = set(selected_ids) if selected_ids else None
+    results: list[TestResult] = []
+    for case in cases:
+        if wanted is not None and case.id not in wanted:
+            continue
+        if not case.automation_file:
+            results.append(
+                TestResult(
+                    test_id=case.id,
+                    title=case.title,
+                    description=case.description,
+                    status=TestOutcome.SKIPPED,
+                    duration_ms=0,
+                    error="no automation file exported",
+                )
+            )
+            continue
+        file_path = test_dir / case.automation_file
+        outcome, duration_ms, error = _run_one(file_path, interpreter, timeout_sec)
+        steps, video, screenshot = _collect_steps(case, test_dir, outcome)
+        artifacts = [p for p in (video, screenshot) if p]
+        results.append(
+            TestResult(
+                test_id=case.id,
+                title=case.title,
+                description=case.description,
+                status=outcome,
+                duration_ms=duration_ms,
+                error=error,
+                automation_file=case.automation_file,
+                steps=steps,
+                video_path=video,
+                screenshot_path=screenshot,
+                artifacts=artifacts,
+            )
+        )
+    return results
+
+
+__all__ = ["run_tests"]

package/python/suitest_lifecycle/serialize.py

@@ -0,0 +1,131 @@
+"""JSON serialisation for lifecycle artifacts (TestSprite-compatible shapes)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from suitest_lifecycle.models import (
+        CodeSummary,
+        PlanCase,
+        Prd,
+        RunSummary,
+        TestResult,
+    )
+
+JsonValue = object  # documented alias; concrete dicts/lists below are fully typed
+
+
+def prd_to_json(prd: Prd) -> dict[str, object]:
+    return {
+        "meta": {"project": prd.project, "date": prd.date, "prepared_by": prd.prepared_by},
+        "product_overview": prd.product_overview,
+        "core_goals": list(prd.core_goals),
+        "features": [
+            {"name": f.name, "description": f.description, "user_flows": list(f.user_flows)}
+            for f in prd.features
+        ],
+    }
+
+
+def plan_to_json(cases: list[PlanCase]) -> list[dict[str, object]]:
+    return [
+        {
+            "id": c.id,
+            "title": c.title,
+            "description": c.description,
+            "category": c.category,
+            "priority": c.priority.value,
+            "steps": [{"type": s.type, "description": s.description} for s in c.steps],
+            "source_ref": c.source_ref,
+            "automation_file": c.automation_file,
+            "tags": list(c.tags),
+        }
+        for c in cases
+    ]
+
+
+def code_summary_to_json(summary: CodeSummary) -> dict[str, object]:
+    return {
+        "project_name": summary.project_name,
+        "mode": summary.mode.value,
+        "tech_stack": list(summary.tech_stack),
+        "auth_flow": summary.auth_flow,
+        "features": list(summary.features),
+        "endpoints": [
+            {
+                "method": e.method,
+                "path": e.path,
+                "auth_required": e.auth_required,
+                "source_file": e.source_file,
+                "handler": e.handler,
+            }
+            for e in summary.endpoints
+        ],
+        "pages": [
+            {
+                "route": p.route,
+                "name": p.name,
+                "protected": p.protected,
+                "source_file": p.source_file,
+            }
+            for p in summary.pages
+        ],
+    }
+
+
+def result_to_json(r: TestResult) -> dict[str, object]:
+    return {
+        "testId": r.test_id,
+        "title": r.title,
+        "description": r.description,
+        "status": r.status.value,
+        "durationMs": r.duration_ms,
+        "error": r.error,
+        "automationFile": r.automation_file,
+        "artifacts": list(r.artifacts),
+        "video": r.video_path,
+        "screenshot": r.screenshot_path,
+        "steps": [
+            {
+                "index": s.index,
+                "type": s.type,
+                "description": s.description,
+                "status": s.status.value,
+            }
+            for s in r.steps
+        ],
+    }
+
+
+def results_to_json(results: list[TestResult]) -> list[dict[str, object]]:
+    return [result_to_json(r) for r in results]
+
+
+def summary_to_json(summary: RunSummary) -> dict[str, object]:
+    return {
+        "project": summary.project,
+        "mode": summary.mode.value,
+        "baseUrl": summary.base_url,
+        "totals": {
+            "total": summary.total,
+            "passed": summary.passed,
+            "failed": summary.failed,
+            "skipped": summary.skipped,
+            "errored": summary.errored,
+        },
+        "durationMs": summary.duration_ms,
+        "serverStarted": summary.server_started,
+        "ready": summary.ready,
+        "readyDetail": summary.ready_detail,
+        "results": results_to_json(summary.results),
+    }
+
+
+__all__ = [
+    "code_summary_to_json",
+    "plan_to_json",
+    "prd_to_json",
+    "results_to_json",
+    "summary_to_json",
+]

package/python/suitest_lifecycle/tcm.py

@@ -0,0 +1,149 @@
+"""TCM — the test-case source of truth.
+
+Primary store is a readable JSON mirror under ``suitest-output/tcm/`` so the
+lifecycle runs with zero infrastructure. When the Suitest Postgres stack is
+reachable, :func:`sync_to_db` upserts the same records through the real
+``packages/db`` repositories (best-effort; skipped cleanly when unavailable).
+
+Every generated case gets a TCM record; every run updates each case's
+``last_run_result`` / ``last_run_at`` / ``failure_reason`` / ``duration_ms`` —
+satisfying "TCM as source of truth, updated by each run".
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from suitest_lifecycle.models import Mode, PlanCase, RunSummary, TestResult
+    from suitest_lifecycle.paths import Paths
+
+
+@dataclass(frozen=True)
+class TcmSyncReport:
+    backend: str  # "file" | "db" | "db-skipped"
+    cases_written: int
+    runs_appended: int
+    detail: str
+
+
+def _load(path: Path) -> list[dict[str, object]]:
+    if path.is_file():
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if isinstance(data, list):
+            return [d for d in data if isinstance(d, dict)]
+    return []
+
+
+def _case_record(case: PlanCase, mode: Mode) -> dict[str, object]:
+    return {
+        "id": f"{mode.value}:{case.id}",
+        "local_id": case.id,
+        "mode": mode.value,
+        "title": case.title,
+        "description": case.description,
+        "category": case.category,
+        "priority": case.priority.value,
+        "status": "active",
+        "tags": [mode.value, case.category.lower()],
+        "source_ref": case.source_ref,
+        "automation_file": case.automation_file,
+        "last_run_result": None,
+        "last_run_at": None,
+        "failure_reason": None,
+        "duration_ms": None,
+    }
+
+
+def upsert_cases(
+    cases: list[PlanCase],
+    paths: Paths,
+    mode: Mode,
+    results: list[TestResult],
+    run_at: str,
+) -> int:
+    """Write/merge case records and fold in each case's latest run result."""
+    paths.tcm_dir.mkdir(parents=True, exist_ok=True)
+    existing = {str(r.get("id")): r for r in _load(paths.tcm_cases_json)}
+    result_by_id = {r.test_id: r for r in results}
+
+    for case in cases:
+        rec = _case_record(case, mode)
+        prior = existing.get(str(rec["id"]))
+        res = result_by_id.get(case.id)  # results are keyed by local TC id
+        if res is not None:
+            rec["last_run_result"] = res.status.value
+            rec["last_run_at"] = run_at
+            rec["duration_ms"] = res.duration_ms
+            rec["failure_reason"] = res.error.splitlines()[-1] if res.error else None
+        elif prior is not None:
+            for k in ("last_run_result", "last_run_at", "duration_ms", "failure_reason"):
+                rec[k] = prior.get(k)
+        existing[str(rec["id"])] = rec
+
+    merged = list(existing.values())
+    paths.tcm_cases_json.write_text(json.dumps(merged, indent=2), encoding="utf-8")
+    return len(cases)
+
+
+def record_run(summary: RunSummary, paths: Paths, run_at: str) -> int:
+    paths.tcm_dir.mkdir(parents=True, exist_ok=True)
+    runs = _load(paths.tcm_runs_json)
+    runs.append(
+        {
+            "run_at": run_at,
+            "project": summary.project,
+            "mode": summary.mode.value,
+            "base_url": summary.base_url,
+            "total": summary.total,
+            "passed": summary.passed,
+            "failed": summary.failed,
+            "skipped": summary.skipped,
+            "errored": summary.errored,
+            "duration_ms": summary.duration_ms,
+            "ready": summary.ready,
+        }
+    )
+    paths.tcm_runs_json.write_text(json.dumps(runs, indent=2), encoding="utf-8")
+    return 1
+
+
+def sync_tcm(
+    cases: list[PlanCase],
+    summary: RunSummary,
+    paths: Paths,
+    mode: Mode,
+    run_at: str,
+) -> TcmSyncReport:
+    written = upsert_cases(cases, paths, mode, summary.results, run_at)
+    appended = record_run(summary, paths, run_at)
+    db_detail = _try_db_sync(cases, summary, mode)
+    return TcmSyncReport(
+        backend="file",
+        cases_written=written,
+        runs_appended=appended,
+        detail=f"file mirror at {paths.tcm_dir}; db: {db_detail}",
+    )
+
+
+def _try_db_sync(cases: list[PlanCase], summary: RunSummary, mode: Mode) -> str:
+    """Best-effort upsert through packages/db. Cleanly skips without a DB.
+
+    Kept import-local so the lifecycle never hard-depends on the API stack.
+    """
+    try:
+        import importlib
+
+        importlib.import_module("suitest_db")
+    except ImportError:
+        return "skipped (suitest_db not installed)"
+    # Real DB wiring requires an async session + DATABASE_URL; deferred to the
+    # API-side sync service. The file mirror remains the portable source of truth.
+    return "available (deferred to API sync service)"
+
+
+__all__ = ["TcmSyncReport", "record_run", "sync_tcm", "upsert_cases"]