stage-cli 1.0.0__py3-none-any.whl

stage/tui/screens/review.py

@@ -0,0 +1,209 @@
+from typing import TYPE_CHECKING
+
+from textual import work
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.screen import Screen
+from textual.widgets import DataTable, Footer, Header, Static, TabbedContent, TabPane
+
+from stage.domain.text import sanitize
+from stage.tui.help import HelpOverlay
+from stage.tui.safe import cell, quoted, told
+
+if TYPE_CHECKING:
+    from stage.storage import AsyncRepository
+
+PAGE = 200
+UNREGISTERED_COLUMNS = ("Employer", "Postings", "Quarantined", "Internships", "Sources")
+QUARANTINE_COLUMNS = ("Reason", "Company", "Title", "Source")
+
+DISPOSITIONS: tuple[tuple[str, str, str], ...] = (
+    ("a", "adapter-candidate", "worth a dedicated adapter"),
+    ("j", "custom-json-candidate", "reachable with a custom board"),
+    ("k", "feed-only", "covered well enough through a feed"),
+    ("u", "unavailable", "no public board to poll"),
+    ("d", "deferred", "revisit later"),
+)
+
+
+HELP_TEXT = """[b]Review[/b]
+  up down  move between rows
+  tab      switch tabs
+
+[b]File an employer[/b]
+  a        worth a dedicated adapter
+  j        reachable with custom json
+  k        covered through a feed
+  u        no public board to poll
+  d        revisit later
+  x        undo the last call
+
+[b]Other[/b]
+  m        load more
+  r        reload from the database
+
+[dim]? closes this   escape goes back[/dim]"""
+
+
+class ReviewScreen(HelpOverlay, Screen[None]):
+    HELP_TEXT = HELP_TEXT
+    BINDINGS = [
+        Binding("a", "classify('adapter-candidate')", "adapter"),
+        Binding("j", "classify('custom-json-candidate')", "custom json"),
+        Binding("k", "classify('feed-only')", "feed only"),
+        Binding("x", "unclassify", "undo"),
+        Binding("question_mark", "help", "keys"),
+        Binding("escape", "back", "back"),
+        Binding("u", "classify('unavailable')", "unavailable", show=False),
+        Binding("d", "classify('deferred')", "defer", show=False),
+        Binding("r", "reload", "reload", show=False),
+        Binding("m", "more", "load more", show=False),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._limit = PAGE
+        self._employers: tuple[str, ...] = ()
+
+    @property
+    def repository(self) -> "AsyncRepository | None":
+        from stage.tui.app import StageApp
+
+        app = self.app
+        return app.repository if isinstance(app, StageApp) else None
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("", id="chips")
+        with TabbedContent(id="tabs"):
+            with TabPane("Unregistered", id="tab-unregistered"):
+                yield DataTable(id="unregistered", cursor_type="row")
+            with TabPane("Quarantine", id="tab-quarantine"):
+                yield DataTable(id="quarantine", cursor_type="row")
+        yield Static("", id="detail")
+        yield Static("", id="help")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self._mark_loading()
+        self.query_one("#unregistered", DataTable).add_columns(*UNREGISTERED_COLUMNS)
+        self.query_one("#quarantine", DataTable).add_columns(*QUARANTINE_COLUMNS)
+        self.load()
+
+    def _mark_loading(self) -> None:
+        self.query_one("#chips", Static).update("[dim]loading…[/dim]")
+
+    def selected_employer(self) -> str | None:
+        table = self.query_one("#unregistered", DataTable)
+        row = table.cursor_row
+        if not self._employers or row < 0 or row >= len(self._employers):
+            return None
+        return self._employers[row]
+
+    @work(exclusive=True)
+    async def load(self) -> None:
+        from stage.companies import RegistryError, load_companies
+        from stage.domain import QuarantineFilters
+        from stage.services.coverage import coverage
+        from stage.services.quarantine import list_quarantined
+
+        repo = self.repository
+        if repo is None:
+            return
+        try:
+            companies = load_companies(None)
+        except RegistryError as exc:
+            self.query_one("#detail", Static).update(f"[red]{quoted(str(exc))}[/red]")
+            return
+        report = await coverage(repo, companies, unregistered=True)
+        listing = await list_quarantined(repo, QuarantineFilters(limit=self._limit))
+
+        rows = report.unregistered[: self._limit]
+        self._employers = tuple(entry.company for entry in rows)
+        unregistered = self.query_one("#unregistered", DataTable)
+        unregistered.clear()
+        for entry in rows:
+            unregistered.add_row(
+                cell(entry.company, 34),
+                cell(str(entry.postings)),
+                cell(str(entry.quarantined)),
+                cell("yes" if entry.posts_internships else "-"),
+                cell(", ".join(entry.sources) or "-", 24),
+            )
+
+        quarantine = self.query_one("#quarantine", DataTable)
+        quarantine.clear()
+        for row in listing.entries:
+            quarantine.add_row(
+                cell(row.reason.value, 22),
+                cell(row.company, 22),
+                cell(row.title_raw, 38),
+                cell(row.source, 14),
+            )
+
+        self.query_one("#chips", Static).update(
+            f"[b]{len(report.unregistered)}[/b] unregistered · "
+            f"[b]{listing.total_matching}[/b] quarantined "
+            f"[dim](showing {len(listing.entries)}, {len(report.classifications)} reviewed)[/dim]"
+        )
+        self._render_help()
+
+    def _render_help(self) -> None:
+        keys = "  ".join(f"[b]{key}[/b] {label}" for key, label, _ in DISPOSITIONS)
+        self.query_one("#detail", Static).update(
+            f"{keys}  [b]x[/b] undo\n[dim]Acts on the highlighted employer. "
+            "m loads more quarantined rows.[/dim]"
+        )
+
+    @work(exclusive=True)
+    async def action_classify(self, disposition: str) -> None:
+        from datetime import UTC, datetime
+
+        from stage.domain import CoverageClassification, CoverageDisposition
+
+        repo = self.repository
+        company = self.selected_employer()
+        if repo is None or company is None:
+            told(self, "Highlight an unregistered employer first.", "warning")
+            return
+        note = next(
+            (why for _, label, why in DISPOSITIONS if label == disposition),
+            "reviewed from the interactive browser",
+        )
+        entry = CoverageClassification(
+            company=company,
+            disposition=CoverageDisposition(disposition),
+            note=note,
+            checked_on=datetime.now(UTC),
+        )
+        replaced = await repo.record_coverage_classification(entry)
+        verb = "Updated" if replaced else "Recorded"
+        told(self, f"{verb} {sanitize(company)} as {disposition}")
+        self.load()
+
+    @work(exclusive=True)
+    async def action_unclassify(self) -> None:
+        repo = self.repository
+        company = self.selected_employer()
+        if repo is None or company is None:
+            told(self, "Highlight an employer first.", "warning")
+            return
+        removed = await repo.clear_coverage_classification(company)
+        if not removed:
+            told(self, f"{sanitize(company)} had no recorded decision.", "warning")
+            return
+        told(self, f"Cleared the decision for {sanitize(company)}")
+        self.load()
+
+    def action_more(self) -> None:
+        self._limit += PAGE
+        self.load()
+
+    def action_reload(self) -> None:
+        self._limit = PAGE
+        self.load()
+
+    def action_back(self) -> None:
+        if self.close_help():
+            return
+        self.dismiss(None)

stage/tui/screens/splash.py

@@ -0,0 +1,37 @@
+from textual.app import ComposeResult
+from textual.containers import Center, Middle
+from textual.screen import Screen
+from textual.widgets import Static
+
+from stage.banner import COMPACT, MIN_WIDE
+from stage.banner import WIDE as BANNER
+from stage.banner import block as _block
+
+DISMISS_AFTER = 1.2
+
+__all__ = ["BANNER", "COMPACT", "DISMISS_AFTER", "MIN_WIDE", "SplashScreen", "_block"]
+
+
+class SplashScreen(Screen[None]):
+    def __init__(self, summary: str, *, dismiss_after: float | None = DISMISS_AFTER) -> None:
+        super().__init__()
+        self._summary = summary
+        self._dismiss_after = dismiss_after
+
+    def compose(self) -> ComposeResult:
+        art = _block(BANNER if self.app.size.width >= MIN_WIDE else COMPACT)
+        hint = self._summary if self._dismiss_after else f"{self._summary}\n\npress any key"
+        with Middle(), Center():
+            yield Static(art, id="splash-art")
+            yield Static(hint, id="splash-stats")
+
+    def on_mount(self) -> None:
+        if self._dismiss_after is not None:
+            self.set_timer(self._dismiss_after, self._done)
+
+    def on_key(self) -> None:
+        self._done()
+
+    def _done(self) -> None:
+        if self.is_current:
+            self.dismiss(None)

stage/tui/screens/stats.py

@@ -0,0 +1,124 @@
+from collections import Counter
+from typing import TYPE_CHECKING
+
+from textual import work
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import VerticalScroll
+from textual.screen import Screen
+from textual.widgets import Footer, Header, Static
+
+from stage.tui.help import HelpOverlay
+from stage.tui.safe import quoted
+
+SAMPLE = 5000
+
+if TYPE_CHECKING:
+    from stage.domain import Job
+    from stage.storage import AsyncRepository
+
+BAR_WIDTH = 28
+TOP_N = 12
+TREND_DAYS = 30
+
+
+def trend(jobs: "tuple[Job, ...]", days: int = TREND_DAYS) -> Counter[str]:
+    from datetime import UTC, datetime, timedelta
+
+    cutoff = datetime.now(UTC) - timedelta(days=days)
+    return Counter(
+        job.first_seen.astimezone().strftime("%m-%d") for job in jobs if job.first_seen >= cutoff
+    )
+
+
+def bars(counts: Counter[str], width: int = BAR_WIDTH, top: int = TOP_N) -> str:
+    if not counts:
+        return "[dim]nothing recorded yet[/dim]"
+    ranked = counts.most_common(top)
+    highest = ranked[0][1] or 1
+    label_width = max(len(name) for name, _ in ranked)
+    return "\n".join(
+        f"{quoted(name):<{label_width}}  [b]{'#' * round(width * value / highest)}[/b] {value}"
+        for name, value in ranked
+    )
+
+
+class StatsScreen(HelpOverlay, Screen[None]):
+    HELP_TEXT = """[b]Statistics[/b]
+  r        reload from the database
+
+[dim]? closes this   escape goes back[/dim]"""
+    BINDINGS = [
+        Binding("question_mark", "help", "keys"),
+        Binding("escape", "back", "back"),
+        Binding("r", "reload", "reload", show=False),
+    ]
+
+    @property
+    def repository(self) -> "AsyncRepository | None":
+        from stage.tui.app import StageApp
+
+        app = self.app
+        return app.repository if isinstance(app, StageApp) else None
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield VerticalScroll(Static("[dim]loading…[/dim]", id="stats-grid"))
+        yield Static("", id="help")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self._mark_loading()
+        self.load()
+
+    def _mark_loading(self) -> None:
+        self.query_one("#stats-grid", Static).update("[dim]loading…[/dim]")
+
+    @work(exclusive=True)
+    async def load(self) -> None:
+        from stage.domain import JobFilters
+        from stage.services.query import list_jobs
+
+        repo = self.repository
+        if repo is None:
+            return
+        listing = await list_jobs(repo, JobFilters(limit=SAMPLE), window_days=None)
+        reasons = await repo.quarantine_reason_counts()
+        self.query_one("#stats-grid", Static).update(
+            self._summary(listing.jobs, reasons, listing.total_matching)
+        )
+
+    def _summary(self, jobs: "tuple[Job, ...]", reasons: dict[str, int], total: int) -> str:
+        if not jobs:
+            return "[dim]No postings yet. Run stage sync first.[/dim]"
+        blocks = (
+            ("Postings by role", Counter(job.role.value for job in jobs)),
+            ("Postings by location", Counter(job.location.value for job in jobs)),
+            ("Postings by term", Counter(job.term for job in jobs)),
+            ("Top employers", Counter(job.company for job in jobs)),
+            ("Postings by source", Counter(job.source for job in jobs)),
+            ("Quarantined by reason", Counter(reasons)),
+        )
+        seen = trend(jobs)
+        scope = (
+            f"[b]{total}[/b] postings\n"
+            if len(jobs) >= total
+            else f"[b]{total}[/b] postings, measured on the most recent {len(jobs)}\n"
+        )
+        parts = [scope]
+        parts.extend(f"\n[b]{title}[/b]\n{bars(counts)}" for title, counts in blocks)
+        if seen:
+            ordered = Counter(dict(sorted(seen.items())))
+            parts.append(
+                f"\n[b]First seen over the last {TREND_DAYS} days[/b]\n"
+                f"{bars(ordered, top=TREND_DAYS)}"
+            )
+        return "\n".join(parts)
+
+    def action_reload(self) -> None:
+        self.load()
+
+    def action_back(self) -> None:
+        if self.close_help():
+            return
+        self.dismiss(None)

stage/tui/screens/sync.py

@@ -0,0 +1,194 @@
+from typing import TYPE_CHECKING
+
+from textual import work
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.screen import Screen
+from textual.widgets import DataTable, Footer, Header, ProgressBar, Static
+
+from stage.tui.help import HelpOverlay
+from stage.tui.safe import cell, quoted
+
+if TYPE_CHECKING:
+    from stage.domain import SyncEvent
+    from stage.storage import AsyncRepository
+
+MAX_WARNINGS = 40
+BAR_WIDTH = 22
+
+
+def source_bar(done: int, total: int, width: int = BAR_WIDTH) -> str:
+    if total <= 0:
+        return "-" * width
+    filled = round(width * min(done, total) / total)
+    return "#" * filled + "-" * (width - filled)
+
+
+class SyncScreen(HelpOverlay, Screen[None]):
+    HELP_TEXT = """[b]Sync[/b]
+  s        start a sync
+  x        cancel the run in progress
+
+[dim]? closes this   escape goes back[/dim]"""
+    BINDINGS = [
+        Binding("s", "start", "start"),
+        Binding("x", "cancel", "cancel"),
+        Binding("question_mark", "help", "keys"),
+        Binding("escape", "back", "back"),
+    ]
+
+    def __init__(self, *, dry_run: bool = False) -> None:
+        super().__init__()
+        self.dry_run = dry_run
+        self._sources: dict[str, tuple[int, int]] = {}
+        self._warnings: list[str] = []
+        self._done = 0
+        self._planned = 0
+        self._fetched = 0
+
+    @property
+    def repository(self) -> "AsyncRepository | None":
+        from stage.tui.app import StageApp
+
+        app = self.app
+        return app.repository if isinstance(app, StageApp) else None
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("", id="chips")
+        yield ProgressBar(total=100, show_eta=False, id="overall")
+        yield DataTable(id="sources", cursor_type="row")
+        yield Static("", id="warnings")
+        yield Static("", id="detail")
+        yield Static("", id="help")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        table = self.query_one("#sources", DataTable)
+        table.add_columns("Source", "Progress", "Done")
+        table.focus()
+        self.query_one("#chips", Static).update(
+            "[dim]Press s to start a sync, x to cancel, esc to go back.[/dim]"
+        )
+        self.query_one("#detail", Static).update(
+            "[dim]A sync fetches every enabled board, classifies what it finds, and "
+            "stores the postings that qualify.[/dim]"
+        )
+
+    @property
+    def running(self) -> bool:
+        from textual.worker import WorkerState
+
+        return any(
+            worker.name == "run_sync" and worker.state is WorkerState.RUNNING
+            for worker in self.workers
+        )
+
+    def action_start(self) -> None:
+        if self.running:
+            self.notify("A sync is already running.", severity="warning")
+            return
+        self._sources.clear()
+        self._warnings.clear()
+        self._done = self._planned = self._fetched = 0
+        self.run_sync()
+
+    def action_cancel(self) -> None:
+        if not self.running:
+            self.notify("Nothing to cancel.", severity="warning")
+            return
+        self.workers.cancel_all()
+        self.query_one("#chips", Static).update("[yellow]Sync cancelled.[/yellow]")
+
+    def action_back(self) -> None:
+        if self.close_help():
+            return
+        self.workers.cancel_all()
+        self.dismiss(None)
+
+    @work(exclusive=True)
+    async def run_sync(self) -> None:
+        from stage.companies import RegistryError, load_companies
+        from stage.services.sync import sync
+
+        repo = self.repository
+        if repo is None:
+            return
+        try:
+            companies = load_companies(None)
+        except RegistryError as exc:
+            self.query_one("#chips", Static).update(f"[red]{quoted(str(exc))}[/red]")
+            return
+        async for event in sync(repo, companies, dry_run=self.dry_run):
+            self._absorb(event)
+
+    def _absorb(self, event: "SyncEvent") -> None:
+        from stage.domain import (
+            CompanyDeferred,
+            CompanyFailed,
+            CompanyFinished,
+            CompanyUnchanged,
+            SourceBlocked,
+            SourceFailed,
+            SourceStarted,
+            SyncFinished,
+            SyncStarted,
+        )
+
+        if isinstance(event, SyncStarted):
+            self._planned = event.companies
+            self.query_one("#overall", ProgressBar).update(total=max(event.companies, 1))
+        elif isinstance(event, SourceStarted):
+            self._sources[event.source] = (0, event.companies)
+        elif isinstance(
+            event, CompanyFinished | CompanyUnchanged | CompanyFailed | CompanyDeferred
+        ):
+            done, total = self._sources.get(event.source, (0, 0))
+            self._sources[event.source] = (done + 1, total)
+            self._done += 1
+            if isinstance(event, CompanyFinished):
+                self._fetched += event.fetched
+            elif isinstance(event, CompanyFailed):
+                self._note(quoted(f"{event.source}/{event.company} - {event.error}"))
+            self.query_one("#overall", ProgressBar).update(progress=self._done)
+        elif isinstance(event, SourceBlocked | SourceFailed):
+            self._note(quoted(f"{event.source} - {getattr(event, 'reason', 'failed')}"))
+        elif isinstance(event, SyncFinished):
+            self._finish(event)
+            return
+        self._paint()
+
+    def _note(self, message: str) -> None:
+        self._warnings.append(message)
+        del self._warnings[:-MAX_WARNINGS]
+
+    def _paint(self) -> None:
+        table = self.query_one("#sources", DataTable)
+        table.clear()
+        for name, (done, total) in sorted(self._sources.items()):
+            mark = " ok" if total and done >= total else ""
+            table.add_row(cell(name, 20), source_bar(done, total), f"{done}/{total}{mark}")
+        self.query_one("#chips", Static).update(
+            f"[b]{self._done}[/b] of {self._planned} boards · "
+            f"[b]{self._fetched}[/b] postings fetched"
+        )
+        if self._warnings:
+            shown = "\n".join(f"  {line}" for line in self._warnings[-8:])
+            self.query_one("#warnings", Static).update(
+                f"\n[yellow]Warnings ({len(self._warnings)})[/yellow]\n{shown}"
+            )
+
+    def _finish(self, event: object) -> None:
+        added = getattr(event, "added", 0)
+        updated = getattr(event, "updated", 0)
+        quarantined = getattr(event, "quarantined", 0)
+        outcome = getattr(getattr(event, "outcome", None), "value", "finished")
+        tone = {"success": "green", "partial": "yellow"}.get(outcome, "red")
+        self._paint()
+        self.query_one("#chips", Static).update(
+            f"[{tone}]{outcome}[/{tone}] — [b]{added}[/b] added, {updated} updated, "
+            f"{quarantined} quarantined"
+        )
+        self.query_one("#detail", Static).update(
+            "[dim]Press escape to go back to the postings browser, or s to sync again.[/dim]"
+        )