holt-cli 0.1.0__py3-none-any.whl

holt/tui/commands.py

@@ -0,0 +1,134 @@
+"""What ctrl+p offers.
+
+Textual gives every app a command palette for free, and out of the box it is
+entirely the framework's own: Keys, Maximize, Screenshot, Theme. Useful while
+building a terminal app, and nothing to do with assessing a repository — someone
+who opened it looking for holt's features found a menu about the toolkit holt
+happens to be written in.
+
+So holt puts its own commands in front of those. Two kinds, and the second is
+the reason this file is worth having:
+
+* **The things the keybindings already do** — assess, discover, models, profile.
+  A palette that lists them is how you find a feature whose key you have not
+  memorised, which is every feature until you have used it a few times.
+* **The things that are true right now** — the runs in flight, and the
+  assessments already stored. Those cannot be keybindings, because they are
+  data. `stop home-assistant/core` is only offerable while that run exists, and
+  the palette is the only surface in the interface that can grow a command for
+  it and then lose it again.
+
+The framework's commands are kept, appended after holt's rather than removed:
+they cost a line each and someone who wants a screenshot of a verdict should be
+able to take one.
+
+They are yielded from *this* provider rather than registered alongside it.
+Textual runs every registered provider concurrently and collects hits as they
+arrive, and `App.COMMANDS` is a set, so two providers produce an order that
+changes between launches — holt's commands on top one time and Textual's the
+next. One provider, yielding in a written order, is the only way to say which
+comes first and mean it.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Iterable
+
+from textual.command import DiscoveryHit, Hit, Hits, Provider
+
+from holt.tui import store
+
+
+class HoltCommands(Provider):
+    """holt's own entries in the command palette."""
+
+    async def discover(self) -> Hits:
+        """What the palette shows before anything is typed."""
+        for name, help_text, callback in self._commands():
+            yield DiscoveryHit(name, callback, help=help_text)
+
+    async def search(self, query: str) -> Hits:
+        matcher = self.matcher(query)
+        for name, help_text, callback in self._commands():
+            score = matcher.match(name)
+            if score > 0:
+                yield Hit(score, matcher.highlight(name), callback, help=help_text)
+
+    # ─── the commands themselves ────────────────────────────────────────────
+
+    def _commands(self) -> Iterable[tuple[str, str, Callable[[], None]]]:
+        """Name, one-line help, and what it does.
+
+        Rebuilt on every open rather than cached, because half of these are
+        about state — a run that has finished must stop being offered as one
+        you can stop.
+        """
+        app = self.app
+        yield from self._runs(app)
+        yield from self._stored(app)
+        yield (
+            "assess a repository",
+            "type an owner/name and press enter",
+            app.go_home,
+        )
+        yield (
+            "find a repository",
+            "screen candidates you have not named yet",
+            lambda: app.push_screen("discover"),
+        )
+        yield (
+            "models",
+            "which model answers each stage, and whether it can be reached",
+            lambda: app.push_screen("models"),
+        )
+        yield (
+            "profile",
+            "the languages and the time you have, used to rank what to read",
+            lambda: app.push_screen("profile"),
+        )
+        yield ("quit holt", "asks first if a run is still in flight", app.action_quit)
+        yield from self._framework(app)
+
+    def _framework(self, app) -> Iterable[tuple[str, str, Callable[[], None]]]:
+        """Textual's own commands, last, in the framework's own order."""
+        try:
+            system = list(app.get_system_commands(self.screen))
+        except Exception:  # noqa: BLE001 - the palette opens even if these do not
+            return
+        for entry in system:
+            name, help_text, callback = entry[0], entry[1], entry[2]
+            # `discover` is the framework's own flag for "list this before
+            # anything is typed". Honoured rather than overridden.
+            if len(entry) > 3 and not entry[3]:
+                continue
+            yield (name, help_text, callback)
+
+    def _runs(self, app) -> Iterable[tuple[str, str, Callable[[], None]]]:
+        """One pair of commands per run in flight. First, because they are live."""
+        for session in getattr(app, "in_flight", []):
+            repo = session.options.repo
+            yield (
+                f"watch {repo}",
+                f"rejoin the assessment in progress · {session.options.mode}",
+                lambda s=session: app.watch_run(s),
+            )
+            yield (
+                f"stop {repo}",
+                "ends the run and keeps nothing it had computed",
+                lambda s=session: app.confirm_stop(s),
+            )
+
+    def _stored(self, app) -> Iterable[tuple[str, str, Callable[[], None]]]:
+        """Assessments already produced, newest first. Reading one costs nothing."""
+        try:
+            entries = app.store.all()
+        except Exception:  # noqa: BLE001 - a palette must not raise over a bad store
+            return
+        for entry in entries:
+            verdict = getattr(entry.assessment.verdict, "value", "")
+            age = store.describe_age(entry.age_seconds)
+            yield (
+                f"open {entry.repo}",
+                f"{verdict.replace('_', ' ')} · assessed {age} · {entry.mode}",
+                lambda e=entry: app.open_stored(e),
+            )

holt/tui/discovery.py

@@ -0,0 +1,305 @@
+"""Finding candidates, live or from a recording, as rows rather than markdown.
+
+Two ways in, and the default matters. **Live** is what the feature is for: a
+GitHub search over what you said you wanted, screened for free as each candidate
+comes back. **Replaying a recording** is a demo of that — the same screening over
+committed fixtures, no token, no network — and it is now something you ask for
+rather than the thing the screen opens on. A page of repositories from a search
+somebody else ran in June is not a result about you, and presenting it as the
+first thing `ctrl+f` does made the feature look like a canned list.
+
+Screening is free in both directions: `screen_records` runs no model, so a live
+sweep spends GitHub API quota and a minute of waiting, and nothing else. The
+model cost lives where it always did — pressing enter on a row starts an
+ordinary assessment run.
+
+The engine returns rendered markdown, which is the right output for a
+file and the wrong one for a screen you navigate: the interface needs the slug
+under the cursor so that pressing enter can assess it. Parsing the markdown back
+into data would make the interface depend on how the report is worded, which is
+exactly the coupling the whole TUI has avoided.
+
+So the screening step is reassembled here from `discover`'s own public parts —
+the session manifest, `screen_root`, and `screen_records`, which is where the
+rule actually lives. Nothing about *what survives* is decided in this file. It
+walks the same candidates in the same order and asks the same function.
+
+The full analysis of survivors is deliberately not reproduced. Assessing a
+repository already has a path through this interface, and a second one would be
+the duplicate way of running a stage that this feature must not become: pressing
+enter on a row starts an ordinary run.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from holt import discover
+from holt.evidence.fixtures import FixtureProvider
+from holt.profile import Profile
+from holt.types import Window
+
+#: The session that ships in the repository. Replays with no token and no key.
+#: Reachable on request; never what the screen opens on.
+DEFAULT_SESSION = "demo"
+
+#: How many candidates a live search sources. The same default `holt discover`
+#: uses, so the two produce comparable sweeps.
+DEFAULT_LIMIT = 25
+
+#: What a screening category means in words, since the engine's labels are
+#: short. A category added later falls through to its own label rather than
+#: being dropped, so a new reason still says something.
+CATEGORY_WORDS = {
+    "registry": "a catalogue, not software",
+    "inactive": "not active enough",
+    "no_outsiders": "no outsider has landed work",
+    "unclear": "not enough evidence",
+    "archived": "archived",
+    "mirror": "a mirror of work done elsewhere",
+}
+
+
+def cut_reason(category: str) -> str:
+    return CATEGORY_WORDS.get(category, category.replace("_", " "))
+
+
+@dataclass(slots=True)
+class Row:
+    """One candidate the recorded search turned up, and what screening said."""
+
+    slug: str
+    description: str
+    language: str
+    stars: int
+    verdict: str
+    #: `None` when the candidate survived screening; otherwise why it was cut.
+    category: str | None
+    reason: str
+
+    @property
+    def survived(self) -> bool:
+        return self.category is None
+
+
+def row_for(candidate: Any, screened: Any) -> Row:
+    """One screened candidate as a row. The only place a `Row` is built.
+
+    Live and replay reach screening by different routes and must not describe
+    it differently, so both come through here.
+    """
+    return Row(
+        slug=candidate.slug,
+        description=(candidate.description or "").strip(),
+        language=candidate.language or "",
+        stars=candidate.stars,
+        verdict=getattr(screened.verdict, "value", str(screened.verdict)),
+        category=screened.category,
+        reason=screened.trace[0] if screened.trace else "",
+    )
+
+
+@dataclass(slots=True)
+class Session:
+    name: str
+    profile_description: str
+    queries: list[str]
+    as_of: datetime
+    rows: list[Row]
+    #: Candidates in the manifest with no recorded evidence. Listed, never
+    #: silently dropped — a search that quietly loses candidates is a search
+    #: whose count means nothing.
+    skipped: list[str]
+
+    @property
+    def survivors(self) -> list[Row]:
+        return [r for r in self.rows if r.survived]
+
+
+def missing_token() -> str | None:
+    """What a live search needs, or None. Checked before a thread starts.
+
+    Only `GITHUB_TOKEN`: screening calls no model, so an OpenAI key is not
+    required to find candidates — only to assess one afterwards. Saying
+    otherwise would turn a free feature into one that looks paid.
+    """
+    if os.environ.get("GITHUB_TOKEN"):
+        return None
+    return (
+        "GITHUB_TOKEN is not set. A live search reads GitHub directly; "
+        "export a token, or put it in .env, and try again."
+    )
+
+
+@dataclass
+class Search:
+    """A live search, running on a worker thread.
+
+    The same shape as `holt.tui.session.Session`, for the same reason: sourcing
+    twenty-five repositories and reading a page of pull-request threads from
+    each is a minute of network, and an interface that blocks on it looks
+    broken. The worker appends; the screen reads what it has not drawn yet.
+    There is no message schema and no lock — one writer, append-only, and a
+    cursor on the reading side, which is how the run stream already works.
+
+    Rows arrive in the order the search returned them, cut ones included. They
+    are deliberately not re-sorted as they land: screening says a candidate is
+    worth a closer look, not that it is better than another one, and a list
+    that rearranged itself under the cursor would be asserting an order the
+    engine never computed.
+    """
+
+    profile: Profile
+    limit: int = DEFAULT_LIMIT
+    rows: list[Row] = field(default_factory=list)
+    #: The searches GitHub was actually asked, filled in before any row lands.
+    queries: list[str] = field(default_factory=list)
+    as_of: datetime | None = None
+    #: How many candidates the search sourced. Zero until sourcing returns.
+    total: int = 0
+    #: Candidates GitHub would not let us read. Listed, never counted as
+    #: rejections — "we could not look" is not "we looked and it failed".
+    skipped: list[str] = field(default_factory=list)
+    error: str | None = None
+    finished: bool = False
+    cancelled: bool = False
+    _thread: threading.Thread | None = None
+    _cancel: threading.Event = field(default_factory=threading.Event)
+
+    # ─── lifecycle ──────────────────────────────────────────────────────────
+
+    def start(self) -> None:
+        if self._thread is not None:
+            raise RuntimeError("search already started")
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def cancel(self) -> None:
+        """Stop after the candidate in flight. Rows already screened are kept:
+        they were free, and they are still true."""
+        self._cancel.set()
+
+    @property
+    def running(self) -> bool:
+        return self._thread is not None and self._thread.is_alive()
+
+    @property
+    def survivors(self) -> list[Row]:
+        return [r for r in self.rows if r.survived]
+
+    @property
+    def screened(self) -> int:
+        return len(self.rows)
+
+    def wait(self, timeout: float | None = None) -> None:
+        """Block until the worker exits. Used by tests."""
+        if self._thread is not None:
+            self._thread.join(timeout)
+
+    def describe(self) -> str:
+        """One line of progress, true at every point in the sweep."""
+        if self.error:
+            return self.error
+        if not self.total:
+            return "searching GitHub for candidates…"
+        head = f"screened {self.screened} of {self.total} at no model cost"
+        head += f" · {len(self.survivors)} worth a closer look"
+        cut = self.screened - len(self.survivors)
+        if cut:
+            head += f" · {cut} cut"
+        if self.skipped:
+            head += f" · {len(self.skipped)} could not be read"
+        if self.cancelled:
+            head += " · stopped"
+        return head
+
+    # ─── the worker ─────────────────────────────────────────────────────────
+
+    def _run(self) -> None:
+        try:
+            search = discover.source_live(self.profile, self.limit)
+            # Set before the first row so a screen drawing progress can say
+            # what was searched for while the slow half is still running.
+            self.queries = list(search.queries)
+            self.as_of = search.as_of
+            self.total = len(search.candidates)
+            for step in search.screen(self._cancel.is_set):
+                if step.result is None:
+                    self.skipped.append(step.candidate.slug)
+                    continue
+                self.rows.append(row_for(step.candidate, step.result))
+            self.cancelled = self._cancel.is_set()
+        except Exception as exc:  # noqa: BLE001 - reported, never a traceback
+            from holt.tui.session import readable
+
+            self.error = readable(exc)
+        finally:
+            self.finished = True
+
+
+def manifest_path_exists(name: str = DEFAULT_SESSION) -> bool:
+    """Whether a recorded session is on disk. Used to skip, never to guess."""
+    try:
+        return discover.manifest_path(name).is_file()
+    except OSError:
+        return False
+
+
+def available() -> list[str]:
+    """Recorded session names, newest first by name."""
+    try:
+        return sorted(p.stem for p in discover.DISCOVER_ROOT.glob("*.json"))
+    except OSError:
+        return []
+
+
+def load(name: str = DEFAULT_SESSION, days: int | None = None) -> Session:
+    """Replay a recorded session's screening step. No model, no network.
+
+    Raises `FileNotFoundError` when the session is not on disk, which the screen
+    turns into a sentence rather than a traceback.
+    """
+    manifest: dict[str, Any] = json.loads(discover.manifest_path(name).read_text())
+    as_of = datetime.fromisoformat(manifest["as_of"])
+
+    from holt.profile import Profile
+
+    profile = Profile(**manifest["profile"])
+    if days:
+        profile.days = days
+
+    provider = FixtureProvider(
+        Window.PRE_T, root=discover.screen_root(name), cutoff=as_of
+    )
+
+    rows: list[Row] = []
+    skipped: list[str] = []
+    for raw in manifest["candidates"]:
+        candidate = discover.Candidate(**raw)
+        try:
+            records = provider.fetch(candidate.slug)
+        except FileNotFoundError:
+            skipped.append(candidate.slug)
+            continue
+        # The rule lives in the engine. This asks it; it does not restate it.
+        screened = discover.screen_records(candidate, records, profile.days)
+        rows.append(row_for(candidate, screened))
+
+    # Survivors first: they are the ones you can act on. Within each group the
+    # search's own order is kept, because reordering would be a claim about
+    # which candidate is better and screening does not make one.
+    rows.sort(key=lambda r: not r.survived)
+
+    return Session(
+        name=name,
+        profile_description=profile.describe(),
+        queries=list(manifest.get("queries", [])),
+        as_of=as_of,
+        rows=rows,
+        skipped=skipped,
+    )

holt/tui/env.py

@@ -0,0 +1,49 @@
+"""Reading `.env`, for the interface only.
+
+`holt analyze` deliberately does not do this: the reproduction path should need
+nothing but `--replay`, and a command whose behaviour depends on an untracked
+file in the working directory is harder to reason about, not easier. The
+interface is the one place where a person is sitting down to do several live
+runs in a row, and re-exporting two variables each time is friction with no
+purpose.
+
+Values already in the environment win. `.env` fills gaps; it never overrides
+something the user set deliberately for one run.
+
+The file is in `.gitignore`. Nothing here writes to it, prints its contents, or
+puts a value in an event, a log line or the interface.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def load(path: str | Path = ".env") -> list[str]:
+    """Set any variables `.env` defines that are not already set.
+
+    Returns the names it filled in — names only, never values — so a caller can
+    say where a credential came from without disclosing it.
+    """
+    file = Path(path)
+    if not file.is_file():
+        return []
+
+    filled: list[str] = []
+    for raw in file.read_text().splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].lstrip()
+        name, sep, value = line.partition("=")
+        if not sep:
+            continue
+        name = name.strip()
+        value = value.strip().strip('"').strip("'")
+        if not name or not value or os.environ.get(name):
+            continue
+        os.environ[name] = value
+        filled.append(name)
+    return filled