cursorfleet 0.1.0__py3-none-any.whl

cursorfleet/tui/gates.py

@@ -0,0 +1,255 @@
+"""Display-only verification observations (v0.1 does NOT enforce gates).
+
+Heuristic command classification may be listed here; it never satisfies a gate
+(ADR 0011). PASS/FAIL gate tiles are intentionally not derived from tier 1-3 data.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from datetime import datetime
+
+from cursorfleet.events.kinds import VERIFICATION_KINDS, EventKind, Outcome
+from cursorfleet.events.models import Event
+from cursorfleet.state.models import utc
+
+GATES: tuple[tuple[str, str], ...] = (
+    ("unit_tests", "Unit tests"),
+    ("integration_tests", "Integration tests"),
+    ("type_check", "Type check"),
+    ("lint", "Lint"),
+    ("security_checks", "Security checks"),
+    ("independent_review", "Independent review"),
+    ("re_review", "Re-review"),
+    ("documentation", "Documentation"),
+    ("ci_status", "CI status"),
+    ("merge_readiness", "Merge readiness"),
+)
+GATE_LABEL = dict(GATES)
+OBSERVABLE = frozenset({"unit_tests", "integration_tests", "type_check", "lint", "security_checks"})
+
+DISPLAY_ONLY = "display-only: v0.1 does not enforce gates"
+
+_SPLIT = re.compile(r"\s*(&&|\|\||;|\|)\s*")
+_WORDS = re.compile(r"[a-z0-9_.\-]+")
+_LINT = {"ruff", "eslint", "flake8", "pylint", "golangci-lint", "shellcheck", "hadolint", "clippy"}
+_TYPE = {"mypy", "pyright", "tsc", "typecheck", "type-check"}
+_SECURITY = {"bandit", "semgrep", "trivy", "audit", "pip-audit", "gitleaks", "security"}
+
+
+@dataclass(frozen=True)
+class GateEvidence:
+    gate: str
+    state: str  # "observed" | "unknown" — never pass/fail for heuristics
+    ts: datetime
+    commit: str | None
+    worktree_id: str | None
+    session_id: str
+    agent: str | None
+    origin: str
+    command: str | None = None
+    note: str | None = None
+    exit_outcome: str | None = None  # ok | failed | unknown from hook
+
+
+@dataclass(frozen=True)
+class GateStatus:
+    gate: str
+    label: str
+    state: str  # not_evaluated | observed | unknown | stale
+    detail: str
+    evidence: GateEvidence | None = None
+    head: str | None = None
+
+
+_UNIT = frozenset(
+    {"pytest", "py.test", "jest", "vitest", "mocha", "rspec", "phpunit", "unittest", "ctest"}
+    | {"tox", "nox", "test"}
+)
+
+
+def _classify_segment(words: list[str]) -> str | None:  # noqa: PLR0911
+    names = words
+    joined = " ".join(names)
+    if any(n in _LINT for n in names) and "format" not in names:
+        return "lint"
+    if any(n in _TYPE for n in names):
+        return "type_check"
+    if any(n in _SECURITY for n in names):
+        return "security_checks"
+    if "integration" in joined or "e2e" in joined:
+        return "integration_tests"
+    if any(n in _UNIT or n.startswith(("test:", "test-")) for n in names):
+        return "unit_tests"
+    if "lint" in joined:
+        return "lint"
+    if "check" in joined and "typ" in joined:
+        return "type_check"
+    return None
+
+
+def classify_command(
+    argv0: str | None, subcommand: str | None, display: str | None
+) -> tuple[list[str], bool]:
+    text = (display or " ".join(p for p in (argv0, subcommand) if p)).lower()
+    parts = _SPLIT.split(text)
+    segments = parts[0::2]
+    separators = parts[1::2]
+    gates: list[str] = []
+    for segment in segments:
+        gate = _classify_segment(_WORDS.findall(segment))
+        if gate is not None and gate not in gates:
+            gates.append(gate)
+    return gates, all(s == "&&" for s in separators)
+
+
+def _outcome_label(outcome: Outcome | None) -> str:
+    if outcome is Outcome.OK:
+        return "ok"
+    if outcome is Outcome.FAILED:
+        return "failed"
+    return "unknown"
+
+
+def evidence_from_events(events: Iterable[Event]) -> list[GateEvidence]:
+    """Heuristic verification observations; never mapped to PASS/FAIL gates."""
+    found: list[GateEvidence] = []
+    for event in events:
+        if event.kind is EventKind.GATE_CHANGED and event.gate is not None:
+            if event.gate.name in GATE_LABEL:
+                found.append(
+                    _evidence(
+                        event,
+                        event.gate.name,
+                        "unknown",
+                        "gate.changed",
+                        note="gate.changed is not tier-4 evidence in v0.1",
+                    )
+                )
+        elif event.kind in VERIFICATION_KINDS and event.command is not None:
+            cmd = event.command
+            gates, all_and = classify_command(cmd.argv0, cmd.subcommand, cmd.display)
+            exit_label = _outcome_label(event.outcome)
+            note = "heuristic observation; not proof of pass or fail"
+            if len(gates) > 1 and not (exit_label == "ok" and all_and):
+                note = "chained command: exit code does not identify which step ran; " + note
+            elif len(gates) > 1:
+                note = "chained && command; " + note
+            shown = cmd.display or " ".join(p for p in (cmd.argv0, cmd.subcommand) if p)
+            origin = (
+                "verification.observed"
+                if event.kind is EventKind.VERIFICATION_OBSERVED
+                else "test.completed"
+            )
+            found.extend(
+                _evidence(
+                    event,
+                    gate,
+                    "observed",
+                    origin,
+                    command=shown,
+                    note=note,
+                    exit_outcome=exit_label,
+                )
+                for gate in gates
+            )
+    return found
+
+
+def _evidence(  # noqa: PLR0913
+    event: Event,
+    gate: str,
+    state: str,
+    origin: str,
+    *,
+    command: str | None = None,
+    note: str | None = None,
+    exit_outcome: str | None = None,
+) -> GateEvidence:
+    return GateEvidence(
+        gate=gate,
+        state=state,
+        ts=utc(event.ts),
+        commit=event.commit,
+        worktree_id=event.worktree_id,
+        session_id=event.session_id,
+        agent=event.agent_id,
+        origin=origin,
+        command=command,
+        note=note,
+        exit_outcome=exit_outcome,
+    )
+
+
+def _same_commit(evidence_commit: str, head: str) -> bool:
+    shorter, longer = sorted((evidence_commit.lower(), head.lower()), key=len)
+    return longer.startswith(shorter)
+
+
+def evaluate(
+    evidence: Iterable[GateEvidence], *, worktree_id: str | None, head: str | None
+) -> list[GateStatus]:
+    latest: dict[str, GateEvidence] = {}
+    for item in evidence:
+        if item.worktree_id != worktree_id:
+            continue
+        current = latest.get(item.gate)
+        if current is None or (item.ts, item.session_id) > (current.ts, current.session_id):
+            latest[item.gate] = item
+    rows: list[GateStatus] = []
+    for gate, label in GATES:
+        found = latest.get(gate)
+        if found is None:
+            why = "not evaluated" if gate in OBSERVABLE else "not evaluated (not observable)"
+            rows.append(GateStatus(gate, label, "not_evaluated", why, None, head))
+            continue
+        rows.append(_judge(gate, label, found, head))
+    return rows
+
+
+def _judge(gate: str, label: str, item: GateEvidence, head: str | None) -> GateStatus:
+    sha = item.commit[:8] if item.commit else None
+    exit_bit = f", exit {item.exit_outcome}" if item.exit_outcome else ""
+    if item.commit is None:
+        return GateStatus(
+            gate,
+            label,
+            "observed",
+            f"heuristic observation{exit_bit}; not bound to a commit",
+            item,
+            head,
+        )
+    if head is None:
+        return GateStatus(
+            gate,
+            label,
+            "observed",
+            f"heuristic observation{exit_bit} @{sha}; HEAD unknown",
+            item,
+            head,
+        )
+    if not _same_commit(item.commit, head):
+        return GateStatus(
+            gate,
+            label,
+            "stale",
+            f"STALE: observation{exit_bit} was @{sha}, HEAD now @{head[:8]}",
+            item,
+            head,
+        )
+    return GateStatus(
+        gate,
+        label,
+        "observed",
+        f"heuristic observation{exit_bit} @{sha} (HEAD)",
+        item,
+        head,
+    )
+
+
+def evaluate_all(
+    evidence: list[GateEvidence], heads: Mapping[str | None, str | None]
+) -> dict[str | None, list[GateStatus]]:
+    return {wt: evaluate(evidence, worktree_id=wt, head=head) for wt, head in heads.items()}

cursorfleet/tui/help.py

@@ -0,0 +1,101 @@
+"""Help screen text (kept as data so tests and docs can assert on it)."""
+
+from __future__ import annotations
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Static
+
+from cursorfleet.tui.gates import DISPLAY_ONLY
+from cursorfleet.tui.layout import SINGLE_BELOW, TILE_FROM
+
+KEYS: tuple[tuple[str, str], ...] = (
+    ("a", "Active run: task-centric roles and instances (default)"),
+    ("u", "Active runs: persisted runs for this repo"),
+    ("o", "Sessions (archive): full session-centric overview"),
+    ("l", "Timeline: filterable event stream (newest first)"),
+    ("w", "Worktrees: branch, HEAD, dirty, ahead/behind, owner"),
+    ("g", "Observations: verification signals, display-only (no pass/fail score)"),
+    ("e", "Evidence: observed runs vs SELF-REPORTED declarations"),
+    ("j / k, arrows", "Move down / up (scrolls the detail when it has focus)"),
+    ("Enter", "Open the detail for the selected item"),
+    ("Esc", "Back: leave detail, close or clear the filter"),
+    ("/", "Filter (timeline: agent: session: kind: risk: source: file: since: until: words)"),
+    ("m", "Timeline: load more events"),
+    ("p", "Pin the selected agent to the top of its lane (this session only)"),
+    ("t", f"Toggle 2x2 tiled panes ({TILE_FROM}+ columns only)"),
+    ("r", "Re-read now (index, git, artifacts); never fetches"),
+    ("Tab", "Move focus between filter, list and detail"),
+    ("?", "This help"),
+    ("q", "Quit"),
+)
+
+HONESTY: tuple[str, ...] = (
+    "CursorFleet v0.1 OBSERVES. It does not enforce, approve or block anything.",
+    "Primary labels: Observed, Declared, Inferred, Unavailable, Conflict (not obs/drv/SELF).",
+    "Detail panes may still show technical source/attribution for power users.",
+    "A silent agent is shown STALE / OFFLINE, never idle. No telemetry means UNKNOWN.",
+    "session_id groups one Cursor chat; it is correlation only, not agent identity.",
+    "Q1 and Q2 (subagent identity in hooks) are OPEN; incomplete lifecycles stay visible.",
+    "Token and cost budgets are unknown: Cursor hooks do not expose them.",
+    f"Observations: {DISPLAY_ONLY}. Each signal stands alone; there is no overall score.",
+    "Cloud agents are not visible. Local Cursor sessions only.",
+    "Status is always written as text; colour is only a hint and NO_COLOR is honoured.",
+)
+
+LAYOUTS: tuple[str, ...] = (
+    f"Under {SINGLE_BELOW} columns: one pane (Enter opens the detail, Esc returns).",
+    f"{SINGLE_BELOW}-{TILE_FROM - 1} columns: list on the left, detail on the right.",
+    f"{TILE_FROM}+ columns: same, or press t for a 2x2 grid of list, detail, recent events "
+    "and gates/worktrees.",
+)
+
+SETUP: tuple[str, ...] = (
+    "No data? Run `cursorfleet init --cursor` to install the hooks, then use Cursor.",
+    "`cursorfleet doctor` explains what is missing.",
+)
+
+
+def help_text() -> Text:
+    text = Text("CursorFleet help\n\n", style="bold")
+    text.append("KEYS\n", style="bold")
+    for key, meaning in KEYS:
+        text.append(f"  {key:<14}", style="bold")
+        text.append(f"{meaning}\n")
+    text.append("\nLAYOUT\n", style="bold")
+    for line in LAYOUTS:
+        text.append(f"  {line}\n")
+    text.append("\nHONESTY\n", style="bold")
+    for line in HONESTY:
+        text.append(f"  {line}\n")
+    text.append("\nSETUP\n", style="bold")
+    for line in SETUP:
+        text.append(f"  {line}\n")
+    text.append("\nPress Esc, ? or q to close.\n", style="dim")
+    return text
+
+
+class HelpScreen(ModalScreen[None]):
+    """Modal help. Closing it never quits the app."""
+
+    BINDINGS = [  # noqa: RUF012 - Textual convention
+        Binding("escape", "close", "Close", show=False),
+        Binding("question_mark", "close", "Close", show=False),
+        Binding("q", "close", "Close", show=False),
+    ]
+    DEFAULT_CSS = """
+    HelpScreen { align: center middle; }
+    HelpScreen > VerticalScroll {
+        width: 90%; max-width: 100; height: 90%; border: round $primary; padding: 0 1;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        with VerticalScroll():
+            yield Static(help_text(), id="help_text")
+
+    def action_close(self) -> None:
+        self.dismiss(None)

cursorfleet/tui/layout.py

@@ -0,0 +1,26 @@
+"""Responsive layout rules (docs/tui.md).
+
+- below 100 columns: ONE pane (the list, or the detail after Enter);
+- 100-159 columns: list + detail side by side;
+- 160+ columns: list + detail, or an optional 2x2 tile grid (``t``).
+
+Four panes are never placed side by side: tiles form a 2x2 grid, so each pane keeps at
+least ~80 columns.
+"""
+
+from __future__ import annotations
+
+SINGLE_BELOW = 100
+TILE_FROM = 160
+
+SINGLE = "single"
+SPLIT = "split"
+TILED = "tiled"
+
+
+def layout_for(width: int, tile_enabled: bool) -> str:
+    if width < SINGLE_BELOW:
+        return SINGLE
+    if width >= TILE_FROM and tile_enabled:
+        return TILED
+    return SPLIT

cursorfleet/tui/theme.py

@@ -0,0 +1,176 @@
+"""Text helpers and styling for the TUI.
+
+Rules enforced here for every screen:
+
+- Untrusted strings (roles, branches, paths, refs) go through :func:`safe` and are placed in
+  ``rich.text.Text`` objects, never in markup strings, so ``[bold]``-style content from a
+  forged artifact cannot restyle or hide the UI.
+- Status is never conveyed by colour alone: every state has a text label and an ASCII
+  marker (:data:`LANE_TAG`, :data:`LANE_MARK`). Colour is only an enhancement and is
+  replaced by bold/dim/reverse when ``NO_COLOR`` is set (:class:`Theme`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from cursorfleet.state.models import Lane, utc
+
+LANE_ORDER: tuple[str, ...] = (
+    Lane.QUEUED.value,
+    Lane.LOADING_CONTEXT.value,
+    Lane.PLANNING.value,
+    Lane.WORKING.value,
+    Lane.VERIFYING.value,
+    Lane.AWAITING_REVIEW.value,
+    Lane.PATCHING.value,
+    Lane.BLOCKED.value,
+    Lane.DONE.value,
+    Lane.STALE_OFFLINE.value,
+    Lane.UNKNOWN.value,
+)
+
+LANE_TAG: dict[str, str] = {
+    "queued": "QUEUED",
+    "loading_context": "LOADING CONTEXT",
+    "planning": "PLANNING",
+    "working": "WORKING",
+    "verifying": "VERIFYING",
+    "awaiting_review": "AWAITING REVIEW",
+    "patching": "PATCHING",
+    "blocked": "BLOCKED",
+    "done": "DONE",
+    "stale_offline": "STALE / OFFLINE",
+    "unknown": "UNKNOWN / NO TELEMETRY",
+}
+
+LANE_MARK: dict[str, str] = {
+    "queued": "[Q]",
+    "loading_context": "[C]",
+    "planning": "[P]",
+    "working": "[W]",
+    "verifying": "[V]",
+    "awaiting_review": "[R]",
+    "patching": "[X]",
+    "blocked": "[!]",
+    "done": "[D]",
+    "stale_offline": "[~]",
+    "unknown": "[?]",
+}
+
+BASIS_TAG: dict[str, str] = {
+    "observed_activity": "observed",
+    "lifecycle_only": "lifecycle-only",
+    "self_reported": "SELF-REPORTED",
+    "derived": "derived",
+    "none": "no telemetry",
+}
+
+_COLOR: dict[str, str] = {
+    "blocked": "bold red",
+    "working": "cyan",
+    "verifying": "magenta",
+    "awaiting_review": "yellow",
+    "patching": "blue",
+    "done": "green",
+    "stale_offline": "dim yellow",
+    "unknown": "dim",
+}
+_MONO: dict[str, str] = {
+    "blocked": "bold reverse",
+    "working": "bold",
+    "verifying": "bold",
+    "awaiting_review": "underline",
+    "patching": "underline",
+    "done": "dim",
+    "stale_offline": "dim italic",
+    "unknown": "dim",
+}
+
+GATE_COLOR = {
+    "pass": "green",
+    "fail": "bold red",
+    "stale": "yellow",
+    "unknown": "dim",
+    "not_evaluated": "dim",
+    "observed": "cyan",
+}
+GATE_MONO = {
+    "pass": "bold",
+    "fail": "bold reverse",
+    "stale": "underline",
+    "unknown": "dim",
+    "not_evaluated": "dim",
+    "observed": "bold",
+}
+
+UNKNOWN_BUDGET = "unknown (not exposed by Cursor hooks)"
+SELF_REPORTED_NOTE = "SELF-REPORTED (an agent's claim, not evidence)"
+
+
+@dataclass(frozen=True)
+class Theme:
+    """Style lookup; ``mono`` drops every colour (``NO_COLOR`` or ``--no-color``)."""
+
+    mono: bool = False
+
+    def lane(self, lane: str) -> str:
+        table = _MONO if self.mono else _COLOR
+        return table.get(lane, "")
+
+    def gate(self, state: str) -> str:
+        return (GATE_MONO if self.mono else GATE_COLOR).get(state, "")
+
+    @property
+    def accent(self) -> str:
+        return "bold" if self.mono else "bold cyan"
+
+    @property
+    def dim(self) -> str:
+        return "dim"
+
+
+def safe(value: object, limit: int = 160) -> str:
+    """Printable, single-line, bounded text for untrusted values."""
+    text = "".join(ch if ch.isprintable() else "?" for ch in str(value))
+    return text if len(text) <= limit else text[: max(limit - 3, 0)] + "..."
+
+
+def short_sha(value: str | None, width: int = 8) -> str:
+    return value[:width] if value else "-"
+
+
+def fmt_ts(value: datetime | None) -> str:
+    """Compact absolute UTC time; the UI states that all times are UTC."""
+    return "-" if value is None else utc(value).strftime("%m-%d %H:%M:%S")
+
+
+def fmt_age(now: datetime, then: datetime | None) -> str:
+    if then is None:
+        return "never"
+    seconds = int((utc(now) - utc(then)).total_seconds())
+    if seconds < 0:
+        return "clock skew"
+    if seconds < 60:
+        return f"{seconds}s ago"
+    if seconds < 3600:
+        return f"{seconds // 60}m ago"
+    if seconds < 86400:
+        return f"{seconds // 3600}h ago"
+    return f"{seconds // 86400}d ago"
+
+
+def fmt_duration(seconds: float) -> str:
+    total = int(seconds)
+    hours, rest = divmod(total, 3600)
+    minutes, secs = divmod(rest, 60)
+    if hours:
+        return f"{hours}h{minutes:02d}m{secs:02d}s"
+    if minutes:
+        return f"{minutes}m{secs:02d}s"
+    return f"{secs}s"
+
+
+def plural(count: int, noun: str) -> str:
+    return f"{count} {noun}" + ("" if count == 1 else "s")